Projects & Agents
An Expeditor project is a GitHub repository with an .expeditor/config.yml file that contains some configuration. In order to create such an Expeditor project, we must have a release branch on a GitHub repository that meets the following criteria.
The GitHub repository belongs to one of the following GitHub organizations. Expeditor functionality is only available to the following Chef Software GitHub organizations. Any GitHub repository — public or private — in one of these organizations can become an Expeditor project simply by following step two.
The GitHub repository contains a configuration file (.expeditor/config.yml) on the master branch. For security purposes, Expeditor requires all modifications to the configuration file to be handled through GitHub's pull request process. Changes made to .expeditor/config.yml and pushed directly to GitHub will not be honored. You must add/modify the file via a GitHub pull request.
While not strictly enforced, we highly encourage Expeditor projects to adhere to the following directory structure.
. ├── .expeditor/ │ ├── buildkite/ │ │ └── ... # scripts that run in Buildkite pipelines │ ├── config.yml │ ├── ... # scripts that run as script actions
Keeping the scripts used within the context of Expeditor (and your Buildkite pipelines) within the .expeditor/ directory allows visitors to your repository to quickly understand where and how they are used.
The .expeditor/config.yml configuration file serves two purposes:
- Document the release processes as a versioned artifact.
- Inform Expeditor what actions to take on your behalf.
Below is the initial template you can use for your .expeditor/config.yml.
# Documentation available at https://expeditor.chef.io/docs/getting-started/ --- # The name we use for this project when interacting with Expeditor Slack App project: alias: <ALIAS> # Slack channel in Chef Software slack to send notifications about build failures, etc slack: notify_channel: <SLACK_CHANNEL> github: # 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 via the Expeditor Slack App. This value must be globally unique.
- The name of the channel (without the
#) in Chef Software's internal slack where you would like notifications sent about actions Expeditor takes on your project.
In the context of your experience with Expeditor, you may see the terms project, agent, and alias used interchangeably. In this section we'll briefly describe the difference between these terms.
The agent is the component of Expeditor that has configuration, subscribes to workloads, and coordinates the execution of action sets against those workloads. Agents can be associated with GitHub repositories, Slack channels, or abstract concepts such as administration.
Agents for GitHub repositories are assigned unique IDs in the form of <GITHUB_REPO>:<RELEASE_BRANCH>. This allows us to easily associate which agent is used for which repository. Here are some sample agent IDs for the chef/chef project:
An alias is a nickname that allows you to reference an Expeditor agent using more user-friendly terminology. You can see example of this in the table below.
Thinking about things in terms of aliases can make certain actions (promotion being the only one at the moment) a bit easier because you can provide the alias instead of the full agent ID.
The term project is used to describe a release branch of a software project that has a release life-cycle managed using Expeditor. We will frequently use the agent ID (e.g. chef/example:master) to concisely refer to this release branch, which can sometimes cause confusion as to whether we are referring to the agent or the project. The safe answer is to assume we're speaking about the project, unless specified otherwise.