Skip to main content

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:master] 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-master-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:{{agent_id}}:*

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:master] 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-master-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:master] 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-master-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:{{agent_id}}:*

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:master] 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-master-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:{{agent_id}}:*

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:master] 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-master-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:master] 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-master-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:master] 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-master-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:master] 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-master-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
builtkite_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]({< ref “/docs/pipelines/habitat.md” >}) 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 master and cleanup the leftovers - any changed files left over at the end of this script will get committed to master.
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.
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:{{agent_id}}:*
    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
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 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:{{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_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 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
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 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:{{agent_id}}:*

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:master_completed:pull_request_merged:chef/example-component:master:*
    actions:
      - bash:.expeditor/update-example-component.sh
.expeditor/back-port-code.sh
#!/bin/bash
set -eou pipefail

version=$(get_github_file $EXPEDITOR_REPO master 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

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:master
{{github_repo}} The name of your GitHub repository. chef/example
{{release_branch}} The name of your release branch. master
{{version_constraint}} The version constraint associated with the current release branch. *