Skip to main content

Getting Started

Expeditor is a release management utility built by Chef Software, Inc. to manage all the various software projects it maintains — open source or otherwise. It allows our teams to automate otherwise manual and repetitive tasks like version bumping, CHANGELOG generation, and release build triggering.

This guide will walk through getting Expeditor set up in a GitHub repository as well as document the primitives included in the utility. If you have any questions, please reach out in the #expeditor-support channel in Chef’s internal workspace, or the #expeditor channel in the Chef Community Slack.

Basic Config

Below is an example of a typical config that will monitor a repo and perform some actions on a PR creation/sync and merge.

  1. For Expeditor to monitor you repo, you need to create a config.yml file located <repo_root>/.expeditor/config.yml
  2. Below are some basic configs to get you started
project:
  alias: example-repo-name

# Slack channel in Chef Software slack to send notifications about build failures, etc
slack:
  notify_channel:
    - example-repo-name-notify

github:
  delete_branch_on_merge: true
  minor_bump_labels:
    - "X-bump-minor-version"
  major_bump_labels:
    - "X-bump-major-version"

pipelines:
  - verify
  - docker/build

subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
    - built_in:bump_version:
        ignore_labels:
          - "X-skip-version-bump"
          - "X-skip-all"
          - "X-docs-only"
    - bash:.expeditor/update_version.sh:
        only_if: built_in:bump_version
    - built_in:update_changelog:
        ignore_labels:
          - "X-skip-changelog"
          - "X-skip-all"
          - "X-docs-only"
    - trigger_pipeline:docker/build:
        ignore_labels:
          - "X-skip-all"
          - "X-docs-only"
          - "X-skip-docker"

Project

project:
  alias: example-repo-name

This is an alternate name that you can use in Slack to reference the repo instead of chef/example-repo-name:main

Slack

slack:
  notify_channel:
    - example-repo-name-notify

This will send the results from a workload run to a specific Slack channel.

Github

github:
  delete_branch_on_merge: true
  minor_bump_labels:
    - "X-bump-minor-version"
  major_bump_labels:
    - "X-bump-major-version"

This setups up some basic settings within Github. delete_branch_on_merge will remove your branch after you merge the code into main. minor_bump_labels or major_bump_lables will allow the user to bump a major or minor version on a PR merge by setting a label on the PR. The bumps will only come into play if you have the action built_in:bump_version specified.

Pipelines

pipelines:
  - verify
  - docker/build

This can setup different pipelines you can request Expeditor to start in Buildkite. The - verify pipeline will run when a PR is created/updated. The definition of which by default is located <repo_root>/.expeditor/verify.pipeline.yml and will be used to create the Buildkite Pipeline. The - docker/build pipeline will be run though only when we execute the action trigger_pipeline. The definition for this is similiar to verify but is named this <repo_root>/.expeditor/build.docker.yml.

Subscriptions

subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
    - built_in:bump_version:
        ignore_labels:
          - "X-skip-version-bump"
          - "X-skip-all"
          - "X-docs-only"
    - bash:.expeditor/update_version.sh:
        only_if: built_in:bump_version
    - built_in:update_changelog:
        ignore_labels:
          - "X-skip-changelog"
          - "X-skip-all"
          - "X-docs-only"
    - trigger_pipeline:docker/build:
        ignore_labels:
          - "X-skip-all"
          - "X-docs-only"
          - "X-skip-docker"

Subscriptions are where you can specify additional actions for Expeditor to take on a repo based on different type of events. The most common type of event is when a PR is merged as shown above. This tells Expeditor that any time a PR is merged we want to run four actions.

The first action is using a built in action called bump_version which will simply update the <repo_root>/VERSION file and either bump the patch, minor, or major section. We have also configured the ignore_labels on the action which will tell Expeditor to skip this action if any of these labels are on the PR.

The second action will call a custom script update_version.sh to do some action that is unique to this repo. It has the only_if modifier which tells us that we only want this action to run when we bump our version.

The third action will use another built in called update_changelog which will simply update the <repo_name>/CHANGELOG.md with the latest changes and like bump_version will skip running if we detect the label.

The final action trigger_pipeline:docker/build tells Expeditor to start a pipeline and in this case it is the docker/build pipeline.

Results

Since we have the Slack configured above, Expeditor will send the results of the workload run pull_request_merged to the slack channel. It will look somthing like:

ExpeditorAPP  10:36 AM
chef/expeditor:main performed the following actions for merged_chef/expeditor#1930 (logs)
• Bumped the main branch of chef/expeditor to 1.6.164
• Executed .expeditor/update_version.sh
• Updated CHANGELOG.md
• Triggered build #145 on the docker/build pipeline

It will indicate Green when all actions have passed or red when one of the actions have failed. In the case of failure, you can click on the (logs) hyperlink to download the results of what happened. You do have to be on the corporate VPN to view this file.