Workloads

artifact_published

An artifact (currently only an Omnibus package) has been published to a channel in Chef’s internal Artifactory.

Workload Format

artifact_published:<CHANNEL>:<PRODUCT_KEY>:<VERSION>

Sample Usage

Run a Bash script that will automatically update a pinning when a new version of Chef Infra Client 15 is released to stable.

.expeditor/config.yml
---
subscriptions:
  - workload: artifact_published:current:chef:15*
    actions:
      - bash.expeditor/update-chef-pinning.sh:
          post_commit: true

.expeditor/update-chef-pinning.sh
#!/bin/bash
set -eou pipefail

sed -i -r "s/^\s*gem \"chef\".*/  gem \"chef\", \"= ${EXPEDITOR_VERSION}\"/" components/gems/Gemfile
sed -i -r "s/^\s*gem \"chef-bin\".*/  gem \"chef-bin\", \"= ${EXPEDITOR_VERSION}\"/" components/gems/Gemfile

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_CHANNEL)

Name	Type	Description
`channel`	String	The name of the release channel (e.g. `stable`)
`product_key`	String	The product key for the product (e.g. `chef`)
`product_name`	String	The full name of the product (e.g. `Chef Infra Client`)
`version`	String	The version of the artifact (e.g. `15.0.0`)

buildkite_build_blocked

A build in one of your pipelines has been blocked.

Workload Format

buildkite_build_blocked:<AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Sample Usage

When the verify/private pipeline becomes blocked because a pull request was opened by an external contributor (as described here), send a message to the team channel (which is different than the general notification channel) to ensure that someone knows that tests are blocked.

.expeditor/config.yml
---
pipelines:
  - verify/public:
      definition: .expeditor/verify_public.pipeline.yml
      public: true
  - verify/private:
      definition: .expeditor/verify_private.pipeline.yml
      public: false

subscriptions:
  - workload: buildkite_build_blocked:{{agent_id}}:verify/private:*
    actions:
      - bash:.expeditor/notify-blocked-pipeline.sh

.expeditor/notify-blocked-pipeline.sh
#!/bin/bash
set -eou pipefail

# Available Formatting: https://api.slack.com/docs/message-formatting
read -r -d '' message <<EOF
<!here> An external contributor has pushed a modification to a pull request and our private verify tests have been blocked.
<https://buildkite.com/${EXPEDITOR_PIPELINE_SLUG}/builds/${EXPEDITOR_BUILD_NUMBER}|Click here> to view the build in question.
Please make sure to review the Pull Request linked in the build to ensure there is no malicious code.
EOF

post_slack_message "our-team-channel" "$message"
post_slack_message "our-notify-channel" "$message"

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PIPELINE_ID)

Name	Type	Description
`pipeline_id`	String	The UUID of the Buildkite pipeline, which can be used with Buildkite’s API.
`pipeline_full_name`	String	The full name of the pipeline (e.g. `[chef/example:main] verify/private`)
`pipeline_name`	String	Expeditor’s short name of the pipeline (e.g. `verify/private`)
`pipeline_slug`	String	The slug for the pipeline (e.g. `chef/chef-example-main-verify-private`), which can be used with Buildkite’s GraphQL API.
`build_id`	String	The UUID of the Buildkite build, which can be used with Buildkite’s GraphQL API.
`build_number`	String	The build number for the pipeline (e.g. `10`)
`build_message`	String	The message passed into the build when it was created (defaults to commit message of commit).
`build_commit`	String	The git SHA used for the build.
`build_branch`	String	The git branch used for the build.
`build_state`	String	The state of the build (`blocked`)

buildkite_build_canceled

A build in one of your pipelines has been successfully canceled.

Workload Format

buildkite_build_canceled:<AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Sample Usage

Unlock the post_merge staging area if a build in the habitat/build pipeline is canceled.

.expeditor/config.yml
---
staging_areas:
  - post_merge:
      workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*

pipelines:
  - habitat/build

subscriptions:
  - workload: staged_workload_released:{{agent_id}}:post_merge:*
    actions:
      - trigger_pipeline:habitat/build
  - workload: buildkite_build_canceled:{{agent_id}}:habitat/build:*
    actions:
      - unlock_staging_area:post_merge

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PIPELINE_ID)

Name	Type	Description
`pipeline_id`	String	The UUID of the Buildkite pipeline, which can be used with Buildkite’s API.
`pipeline_full_name`	String	The full name of the pipeline (e.g. `[chef/example:main] habitat/build`)
`pipeline_name`	String	Expeditor’s short name of the pipeline (e.g. `habitat/build`)
`pipeline_slug`	String	The slug for the pipeline (e.g. `chef/chef-example-main-habitat-build`), which can be used with Buildkite’s GraphQL API.
`build_id`	String	The UUID of the Buildkite build, which can be used with Buildkite’s GraphQL API.
`build_number`	String	The build number for the pipeline (e.g. `10`)
`build_message`	String	The message passed into the build when it was created (defaults to commit message of commit).
`build_commit`	String	The git SHA used for the build.
`build_branch`	String	The git branch used for the build.
`build_state`	String	The state of the build (`canceled`)

buildkite_build_canceling

A build in one of your pipelines is in the process of being canceled.

Workload Format

buildkite_build_canceling:<AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Sample Usage

We haven’t run into a situation where someone might use this workload, but it is available! If you think of a reason, let us know!

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PIPELINE_ID)

Name	Type	Description
`pipeline_id`	String	The UUID of the Buildkite pipeline, which can be used with Buildkite’s API.
`pipeline_full_name`	String	The full name of the pipeline (e.g. `[chef/example:main] verify/public`)
`pipeline_name`	String	Expeditor’s short name of the pipeline (e.g. `verify/public`)
`pipeline_slug`	String	The slug for the pipeline (e.g. `chef/chef-example-main-verify-public`), which can be used with Buildkite’s GraphQL API.
`build_id`	String	The UUID of the Buildkite build, which can be used with Buildkite’s GraphQL API.
`build_number`	String	The build number for the pipeline (e.g. `10`)
`build_message`	String	The message passed into the build when it was created (defaults to commit message of commit).
`build_commit`	String	The git SHA used for the build.
`build_branch`	String	The git branch used for the build.
`build_state`	String	The state of the build (`canceling`)

buildkite_build_failed

A build in one of your pipelines has failed.

Workload Format

buildkite_build_failed:<AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Sample Usage

Unlock the post_merge staging area if a build in the habitat/build pipeline fails.

.expeditor/config.yml
---
staging_areas:
  - post_merge:
      workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*

pipelines:
  - habitat/build

subscriptions:
  - workload: staged_workload_released:{{agent_id}}:post_merge:*
    actions:
      - trigger_pipeline:habitat/build
  - workload: buildkite_build_canceled:{{agent_id}}:habitat/build:*
    actions:
      - unlock_staging_area:post_merge

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PIPELINE_ID)

Name	Type	Description
`pipeline_id`	String	The UUID of the Buildkite pipeline, which can be used with Buildkite’s API.
`pipeline_full_name`	String	The full name of the pipeline (e.g. `[chef/example:main] verify/public`)
`pipeline_name`	String	Expeditor’s short name of the pipeline (e.g. `verify/public`)
`pipeline_slug`	String	The slug for the pipeline (e.g. `chef/chef-example-main-verify-public`), which can be used with Buildkite’s GraphQL API.
`build_id`	String	The UUID of the Buildkite build, which can be used with Buildkite’s GraphQL API.
`build_number`	String	The build number for the pipeline (e.g. `10`)
`build_message`	String	The message passed into the build when it was created (defaults to commit message of commit).
`build_commit`	String	The git SHA used for the build.
`build_branch`	String	The git branch used for the build.
`build_state`	String	The state of the build (`failed`)

buildkite_build_passed

A build in one of your pipelines has completed successfully.

Workload Format

buildkite_build_passed:<AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Sample Usage

Unlock a staging area when a pipeline finishes successfully.

.expeditor/config.yml
---
staging_areas:
  - post_merge:
      workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*

pipelines:
  - deploy/acceptance

subscriptions:
  - workload: staged_workload_released:{{agent_id}}:post_merge:*
    actions:
      - trigger_pipeline:deploy/acceptance
  - workload: buildkite_build_passed:{{agent_id}}:deploy/acceptance:*
    actions:
      - unlock_staging_area:post_merge

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PIPELINE_ID)

Name	Type	Description
`pipeline_id`	String	The UUID of the Buildkite pipeline, which can be used with Buildkite’s API.
`pipeline_full_name`	String	The full name of the pipeline (e.g. `[chef/example:main] verify/public`)
`pipeline_name`	String	Expeditor’s short name of the pipeline (e.g. `verify/public`)
`pipeline_slug`	String	The slug for the pipeline (e.g. `chef/chef-example-main-verify-public`), which can be used with Buildkite’s GraphQL API.
`build_id`	String	The UUID of the Buildkite build, which can be used with Buildkite’s GraphQL API.
`build_number`	String	The build number for the pipeline (e.g. `10`)
`build_message`	String	The message passed into the build when it was created (defaults to commit message of commit).
`build_commit`	String	The git SHA used for the build.
`build_branch`	String	The git branch used for the build.
`build_state`	String	The state of the build (`passed`)

buildkite_build_running

A build in one of your pipelines is currently running jobs.

Workload Format

buildkite_build_running:<AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Sample Usage

We haven’t run into a situation where someone might use this workload, but it is available! If you think of a reason, let us know!

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PIPELINE_ID)

Name	Type	Description
`pipeline_id`	String	The UUID of the Buildkite pipeline, which can be used with Buildkite’s API.
`pipeline_full_name`	String	The full name of the pipeline (e.g. `[chef/example:main] verify/public`)
`pipeline_name`	String	Expeditor’s short name of the pipeline (e.g. `verify/public`)
`pipeline_slug`	String	The slug for the pipeline (e.g. `chef/chef-example-main-verify-public`), which can be used with Buildkite’s GraphQL API.
`build_id`	String	The UUID of the Buildkite build, which can be used with Buildkite’s GraphQL API.
`build_number`	String	The build number for the pipeline (e.g. `10`)
`build_message`	String	The message passed into the build when it was created (defaults to commit message of commit).
`build_commit`	String	The git SHA used for the build.
`build_branch`	String	The git branch used for the build.
`build_state`	String	The state of the build (`running`)

buildkite_build_scheduled

A build in one of your pipelines has yet to start running jobs.

Workload Format

buildkite_build_scheduled:<AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Sample Usage

We haven’t run into a situation where someone might use this workload, but it is available! If you think of a reason, let us know!

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PIPELINE_ID)

Name	Type	Description
`pipeline_id`	String	The UUID of the Buildkite pipeline, which can be used with Buildkite’s API.
`pipeline_full_name`	String	The full name of the pipeline (e.g. `[chef/example:main] verify/public`)
`pipeline_name`	String	Expeditor’s short name of the pipeline (e.g. `verify/public`)
`pipeline_slug`	String	The slug for the pipeline (e.g. `chef/chef-example-main-verify-public`), which can be used with Buildkite’s GraphQL API.
`build_id`	String	The UUID of the Buildkite build, which can be used with Buildkite’s GraphQL API.
`build_number`	String	The build number for the pipeline (e.g. `10`)
`build_message`	String	The message passed into the build when it was created (defaults to commit message of commit).
`build_commit`	String	The git SHA used for the build.
`build_branch`	String	The git branch used for the build.
`build_state`	String	The state of the build (`scheduled`)

buildkite_build_skipped

A build in one of your pipelines, that was previously scheduled, was skipped because it was an intermediate build.

Workload Format

buildkite_build_skipped:<AGENT_ID>:<PIPELINE_NAME>:<BUILD_ID>

Sample Usage

We haven’t run into a situation where someone might use this workload, but it is available! If you think of a reason, let us know!

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PIPELINE_ID)

Name	Type	Description
`pipeline_id`	String	The UUID of the Buildkite pipeline, which can be used with Buildkite’s API.
`pipeline_full_name`	String	The full name of the pipeline (e.g. `[chef/example:main] verify/public`)
`pipeline_name`	String	Expeditor’s short name of the pipeline (e.g. `verify/public`)
`pipeline_slug`	String	The slug for the pipeline (e.g. `chef/chef-example-main-verify-public`), which can be used with Buildkite’s GraphQL API.
`build_id`	String	The UUID of the Buildkite build, which can be used with Buildkite’s GraphQL API.
`build_number`	String	The build number for the pipeline (e.g. `10`)
`build_message`	String	The message passed into the build when it was created (defaults to commit message of commit).
`build_commit`	String	The git SHA used for the build.
`build_branch`	String	The git branch used for the build.
`build_state`	String	The state of the build (`skipped`)

buildkite_hab_build_group_published

A collection of Chef Habitat packages were successfully built and published to the unstable channel of the public Chef Habitat Depot as part of a Chef Habitat Buildkite pipeline.

Workload Format

buildkite_hab_build_group_published:<AGENT_ID>:<GROUP_ID>:<DATE>

Sample Usage

For a good example of how to subscribe to this workload, please check out our Chef Habitat Buildkite pipeline walk-through.

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PKG_IDENTS). Make sure to read our Bash script guide for guidance on how to directly access elements inside Array and Hash metadata from your Bash scripts.

Name	Type	Description
`group_id`	String	The unique identifier (channel name) for the build group.
`pkg_idents`	Hash	A hash of of Chef Habitat `pkg_ident` mapped by `<PKG_NAME>-<PKG_TARGET>`.

docker_image_published

A Docker image is published to the Docker Hub.

Note

A Docker image must be manually configured to send notifications to Expeditor. If you create a new Docker image, please reach out to Release Engineering for help on configuring it to send notifications to Expeditor.

Workload Format

docker_image_published:<NAMESPACE>/<IMAGE_NAME>:<TAG>:<DATE>

Sample Usage

Automatically update the pinning of the chefes/buildkite Docker Image when a new release is updated (as seen here) and open the resulting change as a new pull request, allowing you to confirm whether or not the new image breaks your test suite.

.expeditor/config.yml
subscriptions:
  - workload: docker_image_published:chefes/buildkite:*
    actions:
      - bash:.expeditor/update_docker_image_version_in_verify_pipeline.sh

.expeditor/update_docker_image_version_in_verify_pipeline.sh
#!/bin/bash

set -eou pipefail

# only bump the sha256 digest for the "latest" tag
if [[ "$EXPEDITOR_TAG" != "latest" ]]; then
  exit 0
fi

branch="expeditor/bump-chefes-buildkite"
git checkout -b "$branch"

sed -i -r "s|image_sha256: .+|image_sha256: ${EXPEDITOR_SHA256_DIGEST#"sha256:"}|" .expeditor/verify.pipeline.yml

git add .expeditor/verify.pipeline.yml

# give a friendly message for the commit and make sure it's noted for any future audit of our codebase that no
# DCO sign-off is needed for this sort of PR since it contains no intellectual property
dco_safe_git_commit "Bump chefes/buildkite version"

open_pull_request

# Get back to release branch and cleanup the leftovers - any changed files left over at the end of this script will get committed to the release branch.
git checkout -
git branch -D "$branch"

.expeditor/verify.pipeline.yml
expeditor:
  defaults:
    executor:
      docker:
        image_sha256: a7e1fa7fc3e1d9b91b6d025c5a099b9975c22be24b54275c4857ccb7bfdb89a9

steps:
  - label: "run a thing in docker"
    expeditor:
      executor:
        docker:

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_NAMESPACE)

Name	Type	Description
`namespace`	String	The `tianon` in `tianon/true:latest`.
`image_name`	String	The `true` in `tianon/true:latest`.
`tag`	String	The `latest` in `tianon/true:latest`.
`sha256_digest`	String	The Content Digest for the published image.

hab_package_published

A Habitat package has been published to a channel in the public Chef Habitat Depot.

Note

We only support subscribing to packages that are built using Chef Habitat Buildkite pipelines or promoted using the built_in:promote_habitat_packages action.

Warning

This workload is not currently aware of the pkg_target.

Workload Format

hab_package_published:<CHANNEL>:<PKG_ORIGIN>/<PKG_NAME>/<PKG_VERSION>/<PKG_RELEASE>

Sample Usage

Automatically update version pinnings for one of your pkg_deps when it is promoted to the stable channel. This sample is based on one that was used by the chef/automate project.

.expeditor/config.yml
subscriptions:
  - workload: hab_package_published:stable:chef/inspec/4*
    actions:
      - bash:.expeditor/update-inspec-version.sh

.expeditor/update-inspec-version.sh
#!/bin/bash
set -eou pipefail

branch="expeditor/update-inspec-version"
git checkout -b "$branch"

sed -i -E "s#chef/inspec/[0-9\.]+/[0-9]{14}#chef/inspec/$EXPEDITOR_PKG_VERSION/$EXPEDITOR_PKG_RELEASE#" components/some-component/habitat/plan.sh

git add components/compliance-service/habitat/plan.sh
dco_safe_git_commit "Bump inspec to $EXPEDITOR_PKG_VERSION/$EXPEDITOR_PKG_RELEASE"

open_pull_request

git checkout -
git branch -D "$branch"

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PKG_ORIGIN)

Name	Type	Description
`pkg_origin`	String	The origin for the package.
`pkg_name`	String	The `pkg_name` for the package.
`pkg_version`	String	The `pkg_version` for the package.
`pkg_release`	String	The UTC datetime stamp when the package was built. This value is specified in `YYYYMMDDhhmmss` format.
`pkg_ident`	String	The fully-qualified identifier of a package that consists of `origin/name/version/release`.
`pkg_target`	String	The `pkg_target` for the package (e.g. x86_64-linux)
`channel`	String	The channel to which the package was published.

incident_status_updated

An update to an incident (which includes maintenance windows) for one of the following services:

Workload Format

incident_status_updated:<SERVICE>:<STATUS>:<DATE>

Sample Usage

We haven’t run into a situation where someone might use this workload, but it is available! Right now it’s mostly used to power some internal processes. If you think of a reason to use it in your configuration, let us know!

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_INCIDENT_IMPACT)

Name	Type	Description
`incident_impact`	String	The impact of the incident. `critical` `maintenance` `major` `minor` `none`
`incident_name`	String	The name of the incident.
`incident_status`	String	The current status of the incident (see below)
`incident_timestamp`	String	A timestamp relevant to the incident (see below)
`service`	String	The name of the service (i.e. one of the services listed above).
`update_body`	String	The message sent along with the status update.

Incident Statuses

There are two groups of incident_status.

Type	Status Events
Incident	`identified` `investigating` `resolved` `monitoring` `postmortem`
Maintenance Window	`scheduled` `in_progress` `verifying` `completed`

Timestamps

What the value of incident_timestamp is has different meaning based on incident_status.

`incident_status`	Relevancy of `incident_timestampe`
`monitoring`	When the incident started.
`resolved`	When the incident was resolved.
`scheduled`	When the maintenance is scheduled to start.
`*`	When the incident was last updated.

project_promoted

An Expeditor project was promoted.

Workload Format

project_promoted:<AGENT_ID>:<PROMOTABLE>:<DATE>

Sample Usage

We recommend reading through our promotion guide for a full set of examples on how to use project_promoted given your specific use case.

.expeditor/config.yml
---
subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - ... # will vary based on your use case

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_PROJECT). Make sure to read our Bash script guide for guidance on how to directly access elements inside Array and Hash metadata from your Bash scripts.

Name	Type	Description
`notify_channels`	Array	Additional Slack channels that should be notified when promotion is complete.
`project`	String	The name of the project you are promoting.
`promoter`	String	The Slack username of the person to trigger the promotion.
`promotable`	String	The reference to what that you are promoting. Either a semantic version or a channel (e.g. stable).
`source_channel`	String	The name of the channel in which `promotable` currently exists. May be the same as `promotable`.
`target_channel`	String	The name of the channel to which the `promotable` of `thing` should be promoted.

pull_request_opened

A new GitHub pull request was opened.

Workload Format

pull_request_opened:<REPO>:<BRANCH>:<NUMBER>:<GITHUB_DELIVERY_GUID>

Sample Usage

Post a GitHub comment using the post_github_comment action that welcomes your contributor and gives them some context on what to expect. _This example comes courtesy of the habitat-sh/core-plans repository.

.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_opened:{{github_repo}}:{{release_branch}}:*
    actions:
      - post_github_comment:.expeditor/templates/welcome.mustache

.expeditor/templates/welcome.mustache

Hello {{author}}! Thanks for the pull request!

Here is what will happen next:
1. Your PR will be reviewed by the maintainers.
2. If everything looks good, one of them will approve it, and your PR will be merged.

Thank you for contributing!

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_REPO). Make sure to read our Bash script guide for guidance on how to directly access elements inside Array and Hash metadata from your Bash scripts.

Name	Type	Description
`action`	String	`opened`
`additions`	Integer	The number of lines added in the pull request.
`author`	String	The GitHub user name of the person who opened the pull request.
`branch`	String	The target branch of the pull request (typically your release branch)
`body`	String	The content of the pull request description.
`changed_files`	Integer	The number of files modified in the pull request.
`comments`	Integer	The number of comments associated with the pull request.
`commits`	Integer	The number of commits included in the pull request.
`deletions`	Integer	The number of lines deleted in the pull request.
`event_sender`	String	The GitHub user name of the person who performed the action.
`head`	String	The name of the HEAD ref for the pull request (e.g. the branch name).
`head_repo`	String	The name of the repository from which the pull request was opened. Useful when determining if the pull request was from a fork.
`issue_labels`	Array	Array of GitHub labels applied to the pull request at the time of the event.
`latest_commit`	String	The git SHA of the most recent commit on the HEAD ref.
`merge_commit`	String	The git SHA for the merge commit of the pull request.
`modified_files`	Array	Array containing the names of the files that were modified in the pull request.
`number`	Integer	The identifying number for your pull request.
`previous_commit`	String	The SHA of the most recent commit on HEAD ref before the latest commit.
`repo`	String	The full name of the repository (e.g. `chef/chef`).
`review_comments`	Integer	The number of review comments associated with the pull request.
`title`	String	The title of the pull request.

pull_request_closed

A GitHub pull request was closed without being merged.

Workload Format

pull_request_closed:<REPO>:<BRANCH>:<NUMBER>:<GITHUB_DELIVERY_GUID>

Sample Usage

We haven’t run into a situation where someone might use this workload, but it is available! If you think of a reason, let us know!

Metadata

Name	Type	Description
`action`	String	`closed`
`additions`	Integer	The number of lines added in the pull request.
`author`	String	The GitHub user name of the person who opened the pull request.
`branch`	String	The target branch of the pull request (typically your release branch)
`body`	String	The content of the pull request description.
`changed_files`	Integer	The number of files modified in the pull request.
`comments`	Integer	The number of comments associated with the pull request.
`commits`	Integer	The number of commits included in the pull request.
`deletions`	Integer	The number of lines deleted in the pull request.
`event_sender`	String	The GitHub user name of the person who performed the action.
`head`	String	The name of the HEAD ref for the pull request (e.g. the branch name).
`head_repo`	String	The name of the repository from which the pull request was opened. Useful when determining if the pull request was from a fork.
`issue_labels`	Array	Array of GitHub labels applied to the pull request at the time of the event.
`latest_commit`	String	The git SHA of the most recent commit on the HEAD ref.
`merge_commit`	String	The git SHA for the merge commit of the pull request.
`modified_files`	Array	Array containing the names of the files that were modified in the pull request.
`number`	Integer	The identifying number for your pull request.
`previous_commit`	String	The SHA of the most recent commit on HEAD ref before the latest commit.
`repo`	String	The full name of the repository (e.g. `chef/chef`).
`review_comments`	Integer	The number of review comments associated with the pull request.
`title`	String	The title of the pull request.

pull_request_merged

A GitHub pull request was merged.

Workload Format

pull_request_merged:<REPO>:<BRANCH>:<NUMBER>:<GITHUB_DELIVERY_GUID>

Sample Usage

We recommend that you check out our version management guide for specific examples of how to leverage the pull_request_merged workload.

---
subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - ... # will vary based on your use case

Metadata

Name	Type	Description
`action`	String	`merged` (This differs from the raw GitHub action, which for a merge is ‘closed’)
`additions`	Integer	The number of lines added in the pull request.
`author`	String	The GitHub user name of the person who opened the pull request.
`branch`	String	The target branch of the pull request (typically your release branch)
`body`	String	The content of the pull request description.
`changed_files`	Integer	The number of files modified in the pull request.
`comments`	Integer	The number of comments associated with the pull request.
`commits`	Integer	The number of commits included in the pull request.
`deletions`	Integer	The number of lines deleted in the pull request.
`event_sender`	String	The GitHub user name of the person who performed the action.
`head`	String	The name of the HEAD ref for the pull request (e.g. the branch name).
`head_repo`	String	The name of the repository from which the pull request was opened. Useful when determining if the pull request was from a fork.
`issue_labels`	Array	Array of GitHub labels applied to the pull request at the time of the event.
`latest_commit`	String	The git SHA of the most recent commit on the HEAD ref.
`merge_commit`	String	The git SHA for the merge commit of the pull request.
`modified_files`	Array	Array containing the names of the files that were modified in the pull request.
`number`	Integer	The identifying number for your pull request.
`previous_commit`	String	The SHA of the most recent commit on HEAD ref before the latest commit.
`repo`	String	The full name of the repository (e.g. `chef/chef`).
`review_comments`	Integer	The number of review comments associated with the pull request.
`title`	String	The title of the pull request.

pull_request_synchronized

A new set of commits has been pushed to a GitHub pull request.

Workload Format

pull_request_synchronized:<REPO>:<BRANCH>:<NUMBER>:<GITHUB_DELIVERY_GUID>

Sample Usage

TBD

Metadata

Name	Type	Description
`action`	String	`synchronized`
`additions`	Integer	The number of lines added in the pull request.
`author`	String	The GitHub user name of the person who opened the pull request.
`branch`	String	The target branch of the pull request (typically your release branch)
`body`	String	The content of the pull request description.
`changed_files`	Integer	The number of files modified in the pull request.
`comments`	Integer	The number of comments associated with the pull request.
`commits`	Integer	The number of commits included in the pull request.
`deletions`	Integer	The number of lines deleted in the pull request.
`event_sender`	String	The GitHub user name of the person who performed the action.
`head`	String	The name of the HEAD ref for the pull request (e.g. the branch name).
`head_repo`	String	The name of the repository from which the pull request was opened. Useful when determining if the pull request was from a fork.
`issue_labels`	Array	Array of GitHub labels applied to the pull request at the time of the event.
`latest_commit`	String	The git SHA of the most recent commit on the HEAD ref.
`merge_commit`	String	The git SHA for the merge commit of the pull request.
`modified_files`	Array	Array containing the names of the files that were modified in the pull request.
`number`	Integer	The identifying number for your pull request.
`previous_commit`	String	The SHA of the most recent commit on HEAD ref before the latest commit.
`repo`	String	The full name of the repository (e.g. `chef/chef`).
`review_comments`	Integer	The number of review comments associated with the pull request.
`title`	String	The title of the pull request.

ruby_gem_published

Any Ruby gem (not just those owned by Chef Software) is published to rubygems.org.

Workload Format

The format of your workload in your subscription will depend on the platform of the Ruby gem to which you wish to subscribe.

Gem Platform	Workload Format
`ruby`	`ruby_gem_published:<GEM_NAME>-<VERSION>`
All Others	`ruby_gem_published:<GEM_NAME>-<VERSION>-<PLATFORM>`

Sample Usage

Automatically bump the version pinning in your Gemfile when a new version of a gem dependency is released.

.expeditor/config.yml
---
subscriptions:
  - workload: ruby_gem_published:mixlib-cli-*
    actions:
      - bash:.expeditor/update-gem-dep.sh
  - workload: ruby_gem_published:mixlib-log-*
    actions:
      - bash.expeditor/update-gem-dep.sh

.expeditor/update-gem-dep.sh
#!/bin/bash
set -eou pipefail

branch="expeditor/${EXPEDITOR_GEM_NAME}_${EXPEDITOR_VERSION}"
git checkout -b "$branch"

bundle lock --update

git add .
dco_safe_git_commit "Bump $EXPEDITOR_GEM_NAME to $EXPEDITOR_VERSION"
open_pull_request "$EXPEDITOR_BRANCH"

git checkout -
git branch -D "$branch"

Metadata

Metadata are the values included in the workload. They can be accessed in Bash scripts by prefixing EXPEDITOR_ (e.g. EXPEDITOR_GEM_NAME).

Name	Type	Description
`gem_name`	String	The name of the gem.
`version`	String	The version of the gem.
`platform`	String	The platform for the gem.
`sha`	String	The Git SHA associated with this version of the gem.

schedule_triggered

A workload generated by a schedule defined in a project.

Workload Format

schedule_triggered:<AGENT_ID>:<NAME>:<DATE>

Sample Usage

We recommend you check out our guide on scheduled action sets for guidance on how to leverage the schedule_triggered action.

.expeditor/config.yml
---
schedules:
  - name: sample_schedule
    description: A sample schedule
    cronline: "0 0 * * *"

subscriptions:
  - workload: schedule_triggered:{{agent_id}}:sample_schedule:*
    actions:
      - ... # will vary based on your use case

Metadata

The schedule_triggered workload has no metadata besides the global values.

staged_workload_released

A workload that has been released from a staging area.

Workload Format

staged_workload_released:<AGENT_ID>:<STAGING_AREA_NAME>:<DATE>

Sample Usage

We recommend checking out our guide to staging areas for more information on how best to leverage them.

.expeditor/config.yml
staging_areas:
  - post_merge:
      workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*

pipelines:
  - my_pipeline

subscriptions:
  - workload: staged_workload_released:{{agent_id}}:post_merge:*
    actions:
      - ... # actions may vary based on use case

Metadata

The staged_workload_released workload retains the metadata of the original workload (e.g. pull_request_merged).

<AGENT_ID>_completed

A workload triggered on the completion of the parent workload by a specific agent

Workload Format

<AGENT_ID>_completed:<PARENT_WORKLOAD_ID>

Sample Usage

Run a Bash script that automatically bumps a components that lives in another repository. _If you want to see this pattern in action, check out chef/chef-workstation

.expeditor/config.yml
---
subscriptions:
  - workload: chef/example-component:main_completed:pull_request_merged:chef/example-component:main:*
    actions:
      - bash:.expeditor/update-example-component.sh

.expeditor/back-port-code.sh
#!/bin/bash
set -eou pipefail

version=$(get_github_file $EXPEDITOR_REPO $EXPEDITOR_BRANCH VERSION)
branch="expeditor/example_component_${version}"
git checkout -b "$branch"

sed -i -r "s/override \"example-component\",\s+version: \"v[^\"]+\"/override \"example-component\", version: \"v${version}\"/" omnibus_overrides.rb

git add .

dco_safe_git_commit "Bump Chef Workstation App to $version"

open_pull_request

git checkout -
git branch -D "$branch"

Metadata

A completed workload contains the metadata of the original parent workload.

Reference

Delayed Workloads

There may be times when we want to trigger the actions from a workload on a delay from when we actually received the notification. Right now this happens frequently with services like RubyGems or Omnitruck which can operate on a delay from when their events actually fire. This will allow us to delay workloads to remove some of the pain this may cause and to eliminate the custom scripting to get around this.

Delays can be specified in 3 formats:

s - seconds (ie. 30s)
m - minutes (ie. 1.5m)
h - hours (ie. 1h)

Delays can only be specified with a max value of 1h and no less than 0s.

subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    delay: 1.5m
    actions:
    - built_in:bump_version:
        ignore_labels:
          - "X-skip-version-bump"
          - "X-skip-all"
          - "X-docs-only"

Pull Request Workloads

Instead of creating custom scripts to create pull requests to handle automated tasks, you can have the workload do it for you! You can specify a title, description and branch or omit them to use the default values. You can also simply set pull_request: true to use the defaults as well. Both title and branch can be used with {{mustache}} template variables while the description can be supplied with a file path to a mustache template.

Note

The supported mustache variables are related to the current workloads metadata.

Examples:

subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    pull_request:
      title: "{{name}}"
      description: .expeditor/templates/path_to_template.mustache
      branch: "my-branch"
    actions:
    - bash:.expeditor/update_references.sh

.expeditor/templates/path_to_template.mustache

{{promotable}} was promoted from {{source_channel}} to {{target_channel}} by {{promoter}}

which would render out to look like this:

chef was promoted from unstable to stable by nkierpiec

You can also specify full defaults by simply setting pull_request: true

subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    pull_request: true
    actions:
    - bash:.expeditor/update_references.sh

Or use a combination of defaults and provided values:

subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    pull_request:
      title: "My Cool Title"
    actions:
    - bash:.expeditor/update_references.sh

Default values are:

title: "Changes in response to {{workload_name}}"
branch: "expeditor/{{workload_uid}}"
description: Chef Expeditor took the following actions in response to {{workload_name}}:
                * list of log messages from the actions taken

Global Metadata

The following fields are available on every workload, and are used primarily for routing and other core functionality.

Name	Type	Description
`id`	String	The full (globally unique) workload identifier (e.g. `artifact_published:stable:chef:15.0.0`)
`event`	String	The name of the workload event (e.g. `artifact_published`)
`name`	String	A user-friendly name for the workload frequently used in place of Workload ID in messaging.
`description`	String	A short description of the event frequently used in messaging.
`html_url`	String	An external URL to view the “thing” that triggered the event that can be used in messaging.
`date`	String	The iso8601 timestamp for when the workload was received.
`agent_id`	String	The project agent assigned the workload.

Subscription Template Variables

In projects with complex subscriptions, it can be cumbersome and/or confusing to frequently reference certain values over and over again. To assist with this, Expeditor provides templating variables that can provide clarity to your subscriptions while also making it easier to manage some values that may change regularly.

Variable	Value	Example
`{{agent_id}}`	The name of your Expeditor agent.	`chef/example:main`
`{{github_repo}}`	The name of your GitHub repository.	`chef/example`
`{{release_branch}}`	The name of your release branch.	`main`
`{{version_constraint}}`	The version constraint associated with the current release branch.	`*`