Creating a Project

In order to create an Expeditor project, you must create a branch on a GitHub repository that meets the following criteria:

  1. The GitHub repository must exist in one of the following GitHub organizations:

    • chef
    • chef-cookbooks
    • chef-partners
    • chef-training
    • habitat-sh
    • inspec
    • learn-chef
  2. The chef-ci GitHub user an “Admin” on your GitHub repository

  3. A pull request containing a new Expeditor configuration file (.expeditor/config.yml) has been merged into the master branch of the GitHub repository

Grant the chef-ci user Read permissions to your private repository

This allows Buildkite to clone the private repository. No action is required if your repository is public. If you’re unsure of how to do this, please reach out to Release Engineering in the #releng-support channel.

Creating your .expeditor/config.yml

We recommend that you keep all Expeditor related content in a top-level .expeditor folder. Below is the initial template you can use for your .expeditor/config.yml.

Expeditor will not recognize .expeditor/config.yml files that are pushed to the master branch. You must add the file via a pull request.
# Documentation available at
# The name we use for this project when interacting with Expeditor Slack App
  alias: <YOUR_ALIAS>

# Slack channel in Chef Software slack to send notifications about build failures, etc
  notify_channel: <YOUR_SLACK_CHANNEL>

  # This deletes the GitHub PR branch after successfully merged into the release branch
  delete_branch_on_merge: true
The short-named used for your project. You will use this when referencing your project to the Expeditor Slack App. This value must be globally unique.
The name of the channel in Chef Software’s internal slack where you would like notifications sent about actions Expeditor takes on your project.

Defining projects, agents, and aliases

The Expeditor documentation will use the term “project” to refer to specific branch of a software project. For example, we consider the master and chef-14 release branches of chef/chef to be two separate projects.

Every project in Expeditor is assigned an agent with a unique ID in the form of <GITHUB_REPO>:<RELEASE_BRANCH>. Here are the Agent IDs for the master and chef-14 projects mentioned above:

The agent is responsible for reading the project’s configuration, subscribing to workloads, and coordinating the execution of it’s action sets.

When you need to refer to a specific project you must provide a valid Agent ID. However, as part of your configuration, you can also configure an project.alias for your agent. In certain interactions with Expeditor, you may be able to provide the alias instead of the Agent ID. A good example of this is promoting a project via the Slack.