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.

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

   • github.com/chef
   • github.com/chef-cft
   • github.com/chef-cookbooks
   • github.com/chef-customers
   • github.com/chef-partners
   • github.com/chef-training
   • github.com/habitat-sh
   • github.com/inspec
   • github.com/learn-chef

2. The GitHub repository contains a configuration file (.expeditor/config.yml) on the repository’s default 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.

Creating your Expeditor folder

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.

Your Expeditor Configuration File

The .expeditor/config.yml configuration file serves two purposes:

1. Document the release processes as a versioned artifact.
2. 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

ALIAS

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.

SLACK_CHANNEL

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.

What is the difference between a project, an agent, and an alias?

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.

Agent

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:

• chef/chef:master
• chef/chef:chef-14

Alias

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.

Project

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:main) 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.

Remove a project from Expeditor

To remove a project from Expeditor, all you need to do is delete the .expeditor/config.yml file. When Expeditor detects that the .expeditor/config.yml file has been deleted, it will delete the agent as well as any Buildkite pipelines you may have specified. Everything else it will leave alone.