Skip to main content

Configuration

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

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:

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.

categories

An array of category hashes to use to organize your changelog. The key for each hash is the Github label and the value is the string to use in your changelog.

Default
Two categories that leverage the “bug” and “enhancement” labels that come standard on every GitHub repository.
.expeditor/config.yml
---
changelog:
  categories:
    - "enhancement": "Features & Enhancements"
    - "bug": "Bug Fixes"
Sample Usage
Configuration that leverages a few of the Type labels from the Chef Open Source Communities documentation.
.expeditor/config.yml
---
changelog:
  categories:
    - "Type: Breaking Change": "Breaking Changes"
    - "Type: Bug": "Bug Fixes"
    - "Type: Enhancement": "Features & Enhancements"
Supported Actions
This configuration is used by the following actions:

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:

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:

docker_images

An array of configuration hashes for Docker images that you wish Expeditor to manage.

Default
An empty list
Sample Usage
A simple Docker image (example) that leverages all the default sub-configuration hash values. It will be built using ./Dockerfile and published as chef/example:{{version}}.
.expeditor/config.yml
---
docker_images:
  - example
Supported Actions
This configuration, including all its sub-configuration hash values, are use by the following actions:

#.dockerfile

The path, relative to your context, to the Dockerfile you wish to use to build Docker images.

Default
Dockerfile
Sample Usage
Point to an alternative Dockerfile
.expeditor/config.yml
---
docker_images:
  - example:
      dockerfile: example.dockerfile

#.build_args

A hash of additional build time arguments you wish to pass in to your Docker image build (docker build --build-args)

Default
An empty list
Sample Usage
Overwrite default arguments with Expeditor-specific values
.expeditor/config.yml
---
docker_images:
  - example:
      build_args:
        MY_ARG: "some-value"
        YOUR_ARG: "another value"

#.context

The “context” path, relative to the root of your repository, to pass to the Docker daemon.

Default
Root of the GitHub repository (.)
Sample Usage
Build the docker image using the Dockerfile located in the components/example-docker-image folder.
.expeditor/config.yml
---
docker_images:
  - example:
      context: components/example-docker-image

#.namespace

The namespace to which the Docker image should be uploaded.

Default
chef
Sample Usage
Publish the example Docker image to the devchef namespace, resulting in a Docker image names devchef/example.
.expeditor/config.yml
---
docker_images:
  - example:
      namespace: devchef
Supported Namespaces
The chef-delivery user must have permission to push to the namespace in question.
Namespace Description
chef Official Docker images for Chef products
chefdemo Docker images for officially supported Chef demos
chefes Chef Release Engineering Docker images
chefops Chef Operations Docker images
devchef Docker images used internally by Chef engineers
habitat Chef Habitat related Docker images (e.g. studio images)

#.tags

A list of additional tags you wish to apply to your Docker image when built_in:build_docker_image is executed.

Default
A list containing only the current version.
---
docker_images:
  - example:
      tags:
        - "{{version}}"
Sample Usage
Also apply the unstable tag in addition to the latest version.
.expeditor/config.yml
---
docker_images:
  - example:
      tags:
        - "{{version}}"
        - unstable

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
This configuration is used by an internal cleanup action.

enforce_dco_signoff

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

Default
true
Sample Usage
We do not recommend modifying this setting.
Supported Actions
This configuration is used by an internal process.

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:

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:

release_branch

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 master branch
---
github:
  release_branch:
    - master:
        version_constraint: "*"
Sample Usage
Configure multiple release branches for your software. The master branch will handle your latest major version (2.*) while your 1-stable branch will handle your previous major version (1.*).
.expeditor/config.yml
---
github:
  release_branch:
    - master:
        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.

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:

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:

base_config

Warning

This is advanced usage. Please have Release Engineering double check your first few implementations of this pattern.

This configuration allows you to offload common Expeditor configuration settings to a file hosted in another GitHub repository. This prevents unnecessary duplication of Expeditor configuration that is consistent across a large number of projects. To make sure your project's configuration is kept up to date, your project will automatically subscribe to changes made to the project.base_config.file via a merged Pull Request.

Expeditor resolves all merge conflicts by overwriting the settings specified in the base_config with the setting specified in your .expeditor/config.yml. This includes array settings like subscriptions.

Default
None
Sample Usage
We do not have a sample usage of this configuration yet. If you find yourself using it, please contact Release Engineering.

repo

The full name of the GitHub repository where file is kept.

Default
No default: this setting is required.

branch

The name of the branch in repo where file is kept.

Default
master

file

The path of the file, relative to the repo root.

Default
.expeditor/config.yml

pipelines

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

Pipelines are not automatically deleted as part of Expeditor activities. If you rename a pipeline, or change the visibility via the pipelines.#.public setting, the old pipeline will need to be manually deleted. This is done as to allow the preservation of build history should it be desired.

Default
An empty list
Supported Actions
This configuration value is leveraged by the following actions:

#.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

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

promote:
  channels:
    - unstable
    - current
    - stable
.expeditor/config.yml (without product_key)
---
promote:
  channels:
    - unstable
    - stable
Supported Actions
This configuration value is leveraged by the following actions and Slack commands:

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
---
ruby_gems:
  - 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
---
ruby_gems:
  - 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:{{agent_id}}:*
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:

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.