Configuration

This page documents all the settings available to you in your .expeditor/config.yml configuration file.

artifact_channels

A list of one or more channels through which your software artifacts are promoted.

Default

The default value for this configuration depends on whether or not you have a product_key configured.

.expeditor/config.yml (with product_key)
---
product_key: chef

artifact_channels:
  - unstable
  - current
  - stable

.expeditor/config.yml (without product_key)
---
artifact_channels:
  - unstable
  - stable

Supported Actions

This configuration value is leveraged by the following actions and Slack commands:

beta

The beta configuration category is a hash where configuration that supports proof-of-concept or early access actions.

Default: See sub-categories below.

notify_http_endpoints

An array of one or more unauthenticated REST endpoints where JSON payloads containing workloads can be sent.

This functionality is intended as a proof-of-concept for a more robust notification system.

Default

An empty list

Sample Usage

Configure your project to send workloads to https://example.com/receive_webhook when an action set contains the built_in:notify_external_http_endpoints action.

.expeditor/config.yml
---
beta:
  notify_http_endpoints:
    - https://example.com/receive_webhook

Supported Actions

This configuration is used by the following actions:

built_in:notify_external_http_endpoints

changelog

The changelog configuration category is a hash that handles the configuration that impacts the management of the changelog file.

Default: See sub-categories below.

category_header_prefix

The Markdown heading prefix to prepend to your category header.

Default

H4 header (####)

Sample Usage

We do not recommend modifying this configuration.

Supported Actions

This configuration is used by the following actions:

default_category_header

The category header to use if none of the configured labels are applied to the pull request.

Default

Merged Pull Requests

Sample Usage

We do not recommend modifying this configuration.

Supported Actions

This configuration is used by the following actions:

line_item

The Mustache template to use for your changelog line item.

Default

- {{pr_title}} [#{{pr_number}}](https://github.com/{{github_repo}}/pull/{{pr_number}}) ([{{pr_author}}](https://github.com/{{pr_author}}))

Sample Usage

We do not recommend modifying this configuration.

Supported Mustache Variables

The following variables can be used in your line item template.

Value	Description
`{{version}}`	The contents of github.version_file.
`{{date}}`	The current date in `YYYY-MM-DD` format.
`{{github_repo}}`	The full name (e.g. `chef/chef`) of the github repo.
`{{version_tag}}`	The version formatted how it will be in the git tag.
`{{pr_title}}`	The title of the pull request.
`{{pr_number}}`	The pull request number.
`{{pr_author}}`	The GitHub name of the pull request author.

Supported Actions

This configuration is used by the following actions:

built_in:update_changelog

release_header

The Mustache template to use for your release header.

Default

[v{{version}}](https://github.com/{{github_repo}}/tree/v{{version}}) ({{date}})

Sample Usage

We do not recommend modifying this configuration.

Supported Mustache Variables

The following variables can be used in your release header template.

Value	Description
`{{version}}`	The contents of github.version_file.
`{{date}}`	The current date in `YYYY-MM-DD` format.
`{{github_repo}}`	The full name (e.g. `chef/chef`) of the github repo.
`{{latest_stable}}`	For projects with a product key specified, this returns the latest stable version per mixlib-install.

Supported Actions

This configuration is used by the following actions:

release_header_prefix

The Markdown heading prefix to prepend to your release header.

Default

H2 header (##)

Sample Usage

We do not recommend modifying this configuration.

Supported Actions

This configuration is used by the following actions:

rollup_header

The Mustache template to use for your rollup header.

Default

Changes since {{latest_stable}} release

Sample Usage

Do not mention the specific version of the latest stable release.

.expeditor/config.yml
changelog:
  rollup_header: Changes not yet released to stable

Supported Mustache Variables

The following variables can be used in your release header template.

Value	Description
`{{version}}`	The contents of github.version_file.
`{{date}}`	The current date in `YYYY-MM-DD` format.
`{{github_repo}}`	The full name (e.g. `chef/chef`) of the github repo.
`{{latest_stable}}`	For projects with a product key specified, this returns the latest stable version per mixlib-install.

Supported Actions

This configuration is used by the following actions:

rollup_header_prefix

The Markdown heading prefix to prepend to your rollup header.

Default

H3 header (###)

Sample Usage

We do not recommend modifying this configuration.

Supported Actions

This configuration is used by the following actions:

unreleased_header

The string to use as a release header when the most recent change to the changelog has not been released. This is defined as a pull request that is merged when the VERSION file has not been modified. Defaults to Unreleased.

Default

Unreleased

Sample Usage

We do not recommend modifying this configuration.

Supported Actions

This configuration is used by the following actions:

github

The github configuration category is a hash with information relevant to files or settings in your GitHub repository.

changelog_file

The path to the markdown file, relative to the root of the GitHub repository, where your changelog is kept.

Default

CHANGELOG.md

Sample Usage

We do not recommend modifying this configuration.

Supported Actions

This configuration is used by the following actions:

delete_branch_on_merge

Whether or not to automatically delete a branch after the associated pull request is merged. This functionality is only supported for branches created on the repository in question.

Default

false

Sample Usage

We recommend setting this value to true.

.expeditor/config.yml
---
github:
  delete_branch_on_merge: true

Supported Actions

None. This setting is used to configure GitHub’s ability to automatically delete head branches.

enforce_dco_signoff

Whether or not to enforce the presence of a DCO Sign-off signature on all commits made to the GitHub repository.

When enabled, Expeditor will automatically enforce the associated GitHub Status Check for your release branch(es).

Default: true
Sample Usage: We do not recommend modifying this setting.
Supported Actions: None. This configuration is used by an internal process when a commit is pushed to a pull request.

major_bump_labels

An array of labels that, if one or more are present on a merged pull request, tells the built_in:bump_version action to bump the MAJOR version number instead of the PATCH/BUILD version number.

Default

An empty list

Sample Usage

Configuration that leverages a few of the recommended GitHub labels.

.expeditor/config.yml
---
github:
  major_bump_labels:
    - "Expeditor: Bump Version Major

Supported Actions

This configuration is used with the following actions:

built_in:bump_version

minor_bump_labels

An array of labels that, if one or more are present on a merged pull request, tells the built_in:bump_version action to bump the MINOR version number instead of the PATCH/BUILD version number.

Default

An empty list

Sample Usage

Configuration that leverages a few of the recommended GitHub labels.

.expeditor/config.yml
---
github:
  minor_bump_labels:
    - "Expeditor: Bump Version Minor

Supported Actions

This configuration is used with the following actions:

built_in:bump_version

release_branch

This setting has been deprecated in favor of release_branches.

version_constraint

A glob pattern used to associate which versions of the software projects are associated with the given release branch.

Default: All versions (*)

version_file

The path to the plaintext file, relative to the root of the GitHub repository, where the MAJOR.MINOR.PATCH is kept.

Default

VERSION

Sample Usage

We do not recommend you modify this configuration.

Supported Actions

This configuration is used with the following actions:

version_tag_format

The format you’d like Expeditor to use for the git tags it creates for your version. You can use the {{version}} Mustache variable to specify your own tag format. Defaults to {{version}}.

Default

{{version}}

Sample Usage

Configure Expeditor to create your version tags with the ‘v’ prefix.

.expeditor/config.yml
---
github:
  version_tag_format: "v{{version}}"

Supported Actions

This configuration is used with the following actions:

helm_charts

An array of valid paths to charts within the repository

Default

Empty list

Sample Usage

Package multiple Helm charts within the repo.

.expeditor/config.yml
---
helm_charts:
    - charts/one
    - charts/two
    - random/three

Supported Actions

This configuration is used by the following actions:

built_in:publish_helm_charts

product_key

An array of valid product keys from the PRODUCT MATRIX that are associated with your project.

Default

Empty list

Sample Usage

If your chef/chef, you’ll want to configure yourself with the chef product key.

.expeditor/config.yml
---
product_key:
  - chef

Supported Actions

This configuration is used with the following actions:

This setting is also used in various internal libraries to identify projects as Omnibus projects.

project

The project configuration category is a hash of configuration options related to the management of the Expeditor project and its agent configuration.

alias

An alias, described in more detail here, is an alternate name you can use to reference your agent instead of the fully [agent id]/docs/getting-started/projects/#agent-id.

Default

None

Sample Usage

Refer to the chef/chef:14-stable agent as chef-14.

.expeditor/config.yml
---
project:
  alias: chef-14

Supported Actions

This configuration value can be used in the following Slack commands:

pipelines

An array of pipeline configuration hashes that will automatically be created and configured.

Default

An empty list

Supported Actions

This configuration value is leveraged by the following actions:

trigger_pipeline

#.description

A description of the pipeline. This value is used in the Buildkite UI as well as some messaging within Expeditor.

Default

An empty string

Sample Usage

Briefly describe the difference between the two verify pipelines.

.expeditor/config.yml
---
pipelines:
  - verify/public:
      description: Pull request tests whose logs are visible publicly.
      public: true
  - verify/private:
      description: Pull request tests who logs are only visible to Chef employees.
      public: false

#.definition

The relative path to the pipeline YAML in the local repository. Default value based on name (see below).

Default

The default value depends on the name of the pipeline. If <NAME> contains a slash, it replaces it with an underscore.

Pipeline Prefix	Default Definition Value
`habitat/`	`.expeditor/<NAME with 'habitat/' removed>.habitat.yml`
`omnibus/`	`.expeditor/<NAME with 'omnibus/' removed>.omnibus.yml`
Anything Else	`.expeditor/<NAME>.pipeline.yml`

The usage of habitat.yml and omnibus.yml indicates that they are a shim pipeline definition. You can read more about them in our Chef Habitat and Omnibus pipeline guides respectively.

Sample Usage

Create two pipelines: deploy/staging and deploy/production, both of which use the same pipeline definition file. In this example, we might also want to leverage pipelines.#.env to control behavior within the pipeline.

.expeditor/config.yml
---
pipelines:
  - deploy/production
  - deploy/staging
      definition: .expeditor/deploy_production.omnibus.yml

#.env

An array of environment variable hashes you wish applied to all builds in the pipeline. In each has, the key is the name of the environment variable and the value is the value of the environment variable.

Some pipeline patterns may automatically inject certain environment variables. In those cases, the environment variables available to you will be documented in associated pipeline types documentation.

Default

An empty list

Sample Usage

Ensure that all builds in our omnibus/adhoc pipeline have the ADHOC environment variable set to true.

.expeditor/config.yml
---
pipelines:
  - omnibus/release:
      definition: .expeditor/release.omnibus.yml
  - omnibus/adhoc:
      definition: .expeditor/release.omnibus.yml
      env:
        - ADHOC: true

#.public

Whether or not the build logs for the pipeline should be publicly available.

Default

false

Sample Usage

Create two verify pipelines: one public and one private.

.expeditor/config.yml
---
pipelines:
  - verify/public:
      description: Pull request tests whose logs are visible publicly.
      public: true
  - verify/private:
      description: Pull request tests who logs are only visible to Chef employees.

#.trigger

The mechanism by which builds on the Buildkite pipelines should be triggered.

Default

The default value depends on the name of the pipeline.

Pipeline Prefix	Default Trigger Value
`deploy/`	`default`
`habitat/`	`habitat`
`omnibus/`	`omnibus`
`verify/`	`pull_request`
Anything Else	`default`

Supported #.trigger Types

The following are the triggers supported by Expeditor. More often than not we recommend going with the default trigger setting.

Name	Description
`habitat`	Trigger builds of a Chef Habitat pipeline via the trigger_pipeline action.
`default`	Only trigger builds via the trigger_pipeline action
`omnibus`	Trigger builds of an Omnibus pipeline via the trigger_pipeline action
`pull_request`	Configure Buildkite to directly respond to pull request activity from GitHub (bypassing Expeditor).

Sample Usage

We have a temporary pipeline to verify the habitat plans. It performs a local build, tests it, then throws it away. Its steps should eventually move into the main “verify” pipeline (if fast enough) or this pipeline should be removed in favor of learning about packaging problems after merge.

.expeditor/config.yml
---
pipelines
  - verify
  - verify/habitat:
      trigger: default

promote

The promote configuration category is a hash that contains all of the configuration related directly to the promotion of the project.

actions

Warning

This setting has been deprecated. Please define your promotion actions by subscribing to the project_promoted action as described in our promotion guide.

A list of one or more actions you wish to execute when you promote your artifacts. Under the covers this setting is translated into subscriptions with some logic around what defaults should be.

Default: An empty list

channels

Warning

This setting has been deprecated in favor of artifact_channels.

A list of one or more channels through which your software artifacts are promoted.

Default

The default value for this configuration depends on whether or not you have a product_key configured.

.expeditor/config.yml (with product_key)
---
product_key: chef

artifact_channels:
  - unstable
  - current
  - stable

.expeditor/config.yml (without product_key)
---
artifact_channels:
  - unstable
  - stable

Supported Actions

This configuration value is leveraged by the following actions and Slack commands:

release_branches

An array of release branch configuration hashes. Please check out our version management guide for a walk-through on how this configuration is used.

Default

The repository’s default branch

---
release_branches:
    - main:
        version_constraint: "*"

Sample Usage

Configure multiple release branches for your software. The main branch will handle your latest major version (2.*) while your 1-stable branch will handle your previous major version (1.*).

.expeditor/config.yml
---
release_branches:
    - main:
        version_constraint: "2.*"
    - 1-stable:
        version_constraint: "1.*"

Supported Actions

This configuration is used for internal routing of events only; it is not used by any actions.

rubygems

An array of Ruby gems managed by the project of which Expeditor should be aware.

Default

An empty list

Sample Usage

Specify an array of Ruby gems whose source code is available in this project. For more information on how to build and promote these Ruby gems, check out our Ruby gems pipeline guide.

.expeditor/config.yml
---
rubygems:
  - example
  - example-bin

Supported Actions

This configuration values are leveraged by the following actions:

#.gemspec_path

The path, relative to the root of the GitHub repository, to the directory that contains the .gemspec file.

Default

The root of the GitHub repository (./)

Sample Usage

Specify the paths of several Ruby gems which are stored in a components/ folder.

.expeditor/config.yml
---
rubygems:
  - example:
      gemspec_path: components/example-gem
  - example-bin
      gemspec_path: components/example-gem

schedules

An array of schedule configuration hashes which you can use to execute action sets at specific intervals.

Default: An empty list
Sample Usage: For a detailed walk through of how to set up a schedule, check out our schedule action sets guide.
Supported Actions: This configuration values are leveraged by an internal process that automatically publishes schedule_triggered workloads at the appropriate time.

#.name

The name of your schedule. Must be all lowercase snake case.

Default: No default: this setting is required.

#.description

A user-friendly description of the schedule, used primarily for documentation purposes.

Default: An empty string.

#.cronline

A Fugit compatible cronline (in UTC) to indicate when the schedule should trigger.

Default: No default: this setting is required.

slack

The slack configuration category is responsible for managing all of the configuration related to Expeditor’s various integrations with Slack.

notify_channel

The name of one or more Slack channels in Chef’s internal Slack you want notifications for asynchronous Expeditor activities to go (without #).

Default

An empty list.

Sample Usage

Specify that notifications should be sent to the example-notify Slack channel.

.expeditor/config.yml
---
slack:
  notify_channel:
    - example-notify

Supported Actions

This configuration value is used by a number of internal processes which are responsible for sending notifications to Slack.

private

Whether or not the Slack channel is private.

Default

false

Sample Usage

Specify that notifications should be sent to the private-example-notify private Slack channel.

.expeditor/config.yml
---
slack:
  notify_channel:
    - private-example-notify:
        private: true

staging_areas

An array of named stagings areas configuration hashes that you wish to maintain.

Default

An empty list

Sample Usage

We recommend checking out our in-depth walk-through for examples on how to use staging_areas.

.expeditor/config.yml
---
staging_areas:
  - post_merge:
      workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*

Support Actions

This configuration values are leverage by internally processes that help manage the locking and unlocking of staging areas including, but not limited to, the following actions:

unlock_staging_area

workload

A workload subscription for which workloads should be placed in the staging area instead of the queue.

Default: No default: this setting is required.

Configuration

artifact_channels

beta

notify_http_endpoints

changelog

categories

category_header_prefix

default_category_header

line_item

release_header

release_header_prefix

rollup_header

rollup_header_prefix

unreleased_header

github

changelog_file

delete_branch_on_merge

enforce_dco_signoff

major_bump_labels

minor_bump_labels

release_branch

version_constraint

version_file

version_tag_format

helm_charts

product_key

project

alias

pipelines

#.description

#.definition

#.env

#.public

#.trigger

promote

actions

channels

release_branches

rubygems

#.gemspec_path

schedules

#.name

#.description

#.cronline

slack

notify_channel

private

staging_areas

workload