Skip to main content

Actions

bash

For maximum flexibility, Expeditor can defer to local Bash scripts that you provide for actions which it does not have built-in support. For many reasons, all of these scripts are executed inside a Docker container using a specialized worker container.

Note

If you think your script will take longer than 30 seconds to run, you should run your script in a Buildkite pipeline instead.

By default, script actions run during the pre-commit phase of the action set, regardless of the order of your actions in that action set. Make sure that if you want your script action to run during the post-commit phase, you specify post_commit: true as an action filter.

Default Action Set Order
pre-commit — any modifications made to the git workspace will be committed to the release branch.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
By default — yes — but since you control the content of your Bash script, please use the retriable action filter to indicate if your script is safe to re-run if it fails.
Supported Workloads
This action can be executed in response to any workload. For the project_promoted workload, this action supports both semantic version and “head of channel” promotion patterns.
Sample Usage
Execute the .expeditor/example_script.sh Bash script during the post-commit phase of the action set in response to the pull_request_merged workload.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - bash:.expeditor/example_script.sh:
          post_commit: true

Helper Functions

The following Bash functions are available to you when you use the bash action.

dco_safe_git_commit

Make a git commit with additional commit message lines that allow the commit to pass DCO checks.

Parameters
The dco_safe_git_commit function accepts the following ordered parameters:
  1. The contextual message (e.g. “Ran my script and did some things”).
Required Environment Setup
The open_pull_request helper requires the following environment setup. This is handled automatically for you in Expeditor, but will need to be handled by you if the script is run manually.
  • The git CLI must be configured with credentials which have write permissions to the GitHub repository so it can push the commit to the release branch.
Sample Usage
See open_pull_request

get_github_file

Write the contents of the given file directly from GitHub to STDOUT.

Parameters
The get_github_file function accepts the following ordered parameters:
  1. The repository (e.g. chef/chef-dk).
  2. The branch from which to download the file (e.g. main).
  3. The path, relative to the project root, where you wish to download the file.
Required Environment Setup
The get_github_file helper requires the following environment setup. This is handled automatically for you in Expeditor, but will need to be handled by you if the script is run manually.
  • The GITHUB_TOKEN environment variable that contains an access token with repo permissions for the GitHub repository so it can fetch the file via the GitHub API.
Sample Usage
Download the VERSION file from the main branch of chef/chef into CHEF_VERSION. 
get_github_file chef/chef main VERSION > CHEF_VERSION

open_pull_request

Open a pull request against the GitHub repository. This provides an alternative to committing changes directly to the release branch.

Parameters
The open_pull_request function accepts the following ordered parameters:
  1. The branch against which to open the pull request (defaults to the current release branch)
Required Environment Setup
The open_pull_request helper requires the following environment setup. This is handled automatically for you in Expeditor, but will need to be handled by you if the script is run manually.
  • The git CLI must be configured with credentials which have write permissions to the GitHub repository so it can push the pull request branch.
  • The GITHUB_TOKEN environment variable that contains an access token with repo permissions for the GitHub repository so it can open the pull request from the branch.
Sample Usage
Open a pull request from the expeditor/update-deps branch which contains a commit containing the results of running the rake update-deps command. 
# Check out a branch on which to perform the work
branch="expeditor/run-myscript"
git checkout -b "$branch"

# Run the command which will modify some files
rake update-deps

# Commit the changes to $branch
git add .
dco_safe_git_commit "Ran some awesome stuff!"

# Open the pull request
open_pull_request

# Get back to the 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"

post_slack_message

Post a plain-text message to one of Chef’s internal Slack channels.

Parameters
The post_slack_message function accepts the following ordered parameters:
  1. The name of the public Slack channel in the Chef workspace (no octothorp).
  2. The string contents of the message.
Required Environment Setup
The post_slack_message helper requires the following environment setup. This is handled automatically for you in Expeditor, but will need to be handled by you if the script is run manually.
  • The VAULT_ADDR, VAULT_NAMESPACE, and VAULT_TOKEN environment variables must be configured to talk to Chef’s internal Vault instance so the helper can fetch the necessary credentials to post to Chef’s Slack workspace.
Sample Usage
Post a message to the random channel. 
read -r -d '' MESSAGE <<'EOF'
This is a simple way to make a nice, neat multiple line string.

It will handle both ' and " by default, so you don't have to worry!
EOF

post_slack_message "random" "$MESSAGE"

post_discourse_release_announcement

Make a post to the Release Announcements category on Chef’s Discourse.

Parameters
The post_discourse_release_announcement function accepts the following ordered parameters:
  1. The title of the post.
  2. The string contents of the message.
Required Environment Setup
The post_discourse_release_announcement helper requires the following environment setup. This is handled automatically for you in Expeditor, but will need to be handled by you if the script is run manually.
  • The VAULT_ADDR, VAULT_NAMESPACE, and VAULT_TOKEN environment variables must be configured to talk to Chef’s internal Vault instance so the helper can fetch the necessary credentials to post to Chef’s Discourse.
Sample Usage
Post a message with the title “New Chef Infra Client Released” to Discourse. 
read -r -d '' MESSAGE <<'EOF'
This is a simple way to make a nice, neat multiple line string.

It will handle both ' and " by default, so you don't have to worry!
EOF

post_discourse_release_announcement "New Chef Infra Client Released" "$MESSAGE"

built_in:build_gem

When a pull request is merged, Expeditor will build the specified Ruby gems and upload them to Chef’s internal Artifactory. For more details on this pattern, please check out our Ruby gems pipeline guide.

Warning

Do not use this action for gems also built as part of their Omnibus package.
Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Build the ohai gem when a pull request is merged.
.expeditor/config.yml
---
rubygems:
  - ohai

subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - built_in:build_gem

built_in:bump_version

For full details on how to use this action, we encourage you to read our version management guide.

Default Action Set Order
pre-commit — any modifications made to the git workspace will be committed to the release branch.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Please check out our version management guide for examples on how to use this action.

built_in:create_github_release

Create a GitHub release record on GitHub when an artifact is published to a specific channel (we recommend stable).

  • The name of the release follows the pattern {{product_name}} {{version_tag_format}}.
  • The body of the release entry will be the content from the <!-- latest_stable_release --> comment block in your changelog file. If you do not use the recommended changelog management patterns, the body of your releases will be empty.
  • This action does not currently support attaching files to GitHub releases.
Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
No - this action can not be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Create a GitHub release when the Chef Inspec artifact is published to the stable channel.
.expeditor/config.yml
---
product_key: inspec

github:
  version_tag_format: 'v{{version}}'

subscriptions:
  - workload: artifact_published:stable:inspec:{{version_constraint}}
    actions:
      - built_in:create_github_release

built_in:github_auto_assign_author

Self-assign the author of the pull request when it is opened.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Automatically self-assign the pull request to the user who opened it if they belong to the team specified in the only_if_team_member action filter.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_opened:{{github_repo}}:{{release_branch}}:*
    actions:
      - built_in:github_auto_assign_author:
          only_if_team_member:
            - chef/example-team

built_in:notify_chefio_slack_channels

Sends a Slack message to the list of Slack channels configured in slack.notify_channel. The content of the message will vary depending on the workload used in the subscription.

When a promotion is triggered by the /expeditor promote Slack command, the channel from which the command was run will be included in the list of channels to be notified should this action be one of the actions in the action set.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Notify the #example-notify channel when the Chef Infra Client omnibus package is published to stable.
.expeditor/config.yml
---
slack:
  notify_channel:
    - example-notify

subscriptions:
  - workload: artifact_published:stable:chef:*
    actions:
      - built_in:notify_chefio_slack_channels

built_in:notify_external_http_endpoints

Make a HTTP POST request to the URLs configured in beta.notify_http_endpoints. The contents of the request is that of the original workload handled by Expeditor.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Send a copy of the artifact_published workload to http://api.example.com/receive_webhook.
.expeditor/config.yml
---
beta:
  notify_http_endpoints:
    - http://api.example.com/receive_webhook

subscriptions:
  - workload: artifact_published:stable:chef:{{version_constraint}}
    actions:
      - built_in:notify_external_http_endpoints

built_in:promote_artifactory_artifact

Promote a version of an artifact in Chef Software’s internal Artifactory instance to it’s next logical channel (as defined in artifact_channels).

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Current Limitations
This action only supports promoting from the current to the stable channel. If the artifact is not already in the current channel in Artifactory, the action will fail.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Promote the Chef Infra Client Omnibus binary from current to stable. For more detail on how to use this action, please check out our promotion guide.
.expeditor/config.yml
---
product_key: chef

artifact_channels:
  - unstable
  - current
  - stable

subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - built_in:promote_artifactory_artifact

built_in:promote_docker_images

Promote the Docker images defined in your dobi.yaml by tagging them with the appropriate tags based on your Dobi annotation tags. Tags can be configured using your default-tags and final-channel-tags Dobi annotations.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
When Chef Infra Client is promoted to current or stable, update the tag for the Docker image accordingly.
.expeditor/config.yml (mixlib-install projects)
---
product_key: chef

pipelines:
  - docker/build

subscriptions:
  - workload: artifact_published:unstable:chef:{{version_constraint}}
    actions:
      - trigger_pipeline:docker/build
  - workload: artifact_published:current:chef:{{version_constraint}}
    actions:
      - built_in:promote_docker_images
  - workload: artifact_published:stable:chef:{{version_constraint}}
    actions:
      - built_in:promote_docker_images
.expeditor/config.yml (general)
---
pipelines:
  - docker/build

subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - trigger_pipeline:docker/build
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - built_in:promote_docker_images
dobi.yaml
image=chef:
  image: '{env.IMAGE_REGISTRY}/chef'
  context: .
  tags:
    - '{env.EXPEDITOR_VERSION}'
  args:
    VERSION: '{env.EXPEDITOR_VERSION}'
    CHANNEL: unstable
  annotations:
    tags:
      - expeditor:default-tags={{channel}}
      - expeditor:final-channel-tags={{major}},{{major}}.{{minor}},latest

built_in:promote_habitat_packages

Promote the Chef Habitat packages configured in your .bldr.toml to the appropriate channel. In addition, if you specify the docker export in your .bldr.toml, this action will also tag the associated Docker image with the appropriate channel as well.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
The usage pattern for this action depends on whether you’re using semantic version and “head of channel” promotion. Please check out our Chef Habitat Buildkite pipeline guide and our promotion guide for the correct usage based on your requirements.

built_in:publish_helm_charts

Publish helm chart(s) to Artifactory Artifactory Production.

Default Action Set Order
pre-commit — any modifications made to the git workspace will be committed to the release branch.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Package the charts located at charts/example, charts/example-bin, and random/example. Publish the charts to Chef’s internal Artifactory located at Artifactory.
.expeditor/config.yml
---
helm_charts:
  - charts/example
  - charts/sub/example-bin
  - random/example

subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    actions:
      - built_in:publish_helm_charts

built_in:publish_rubygems

Copy a Ruby gem from Chef’s internal Artifactory RubyGems repository to rubygems.org.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Copy the promoted version of the example and example-bin Ruby gems from Chef’s internal Artifactory instance to rubygems.org. For more detail on promoting Ruby gems, check out our promotion guide.
.expeditor/config.yml
---
rubygems:
  - example
  - example-bin

subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - built_in:publish_rubygems

built_in:rollover_changelog

Update your changelog to reflect the fact that a specific version was promoted to a channel. In almost all cases, this action should be limited to the stable channel. For more information about what this action does to your changelog, please review the changelog documentation.

Default Action Set Order
pre-commit — any modifications made to the git workspace will be committed to the release branch.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Update your changelog to reflect the promotion of an artifact to your latest stable channel. For more detail on rolling over your changelog, check out our changelog management guide.
.expeditor/config.yml
---
subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - built_in:rollover_changelog

built_in:update_changelog

Add a line item with the title of your GitHub pull request when it is merged. See the changelog documentation for more information about how to setup your changelog.

Default Action Set Order
pre-commit — any modifications made to the git workspace will be committed to the release branch.
Composite Workload Support
This action will add a line item for each workload in a composite workload.
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Add the title of the pull request as a line item in your changelog. See our changelog management guide for more details on how to use this action.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - built_in:update_changelog

create_github_issue

Create a GitHub issue on the current repository in response to an event.

Default Action Set Order
pre-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Supported Workloads
This action can be executed in response to any workload.
Sample Usage
Create a GitHub issue on the current repository.
.expeditor/config.yml
---
subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - create_github_issue:.expeditor/templates/create_issue.mustache:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - create_github_issue:.expeditor/templates/create_issue.mustache:

lock_staging_area

Lock the staging area, allowing for new workloads to be executed.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to any workload. For the project_promoted workload, this action supports both semantic version and “head of channel” promotion patterns.
Sample Usage
Lock the post_merge staging area when the habitat/build pipeline fails. We recommend checking out our staging area guide for more information.
.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_failed:{{agent_id}}:habitat/build:*
    actions:
      - lock_staging_area:post_merge

post_github_comment

In response to a pull request workload (most commonly pull_request_opened), submit a comment based on a Mustache template. The mustache template has access to all of the workload metadata.

Default Action Set Order
pre-commit — any modifications made to the git workspace will be committed to the release branch.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Supported Workloads
This action can be executed in response to the following workloads:
Sample Usage
Post a welcome message when a pull request is opened by someone not on the maintainer team.
.expeditor/config.yml
---
subscriptions:
  - workload: pull_request_opened:{{github_repo}}:{{release_branch}}:*
    actions:
      - post_github_comment:.expeditor/templates/welcome.mustache:
          ignore_team_members:
            - chef/example-maintainers
.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!

purge_packages_chef_io_fastly

Purge the key from the packages.chef.io Fastly cache.

The action name supports Mustache settings for all Workload metadata values (see example below).

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Supported Workloads
This action can be executed in response to any workload. For the project_promoted workload, this action supports both semantic version and “head of channel” promotion patterns.
Sample Usage
Automatically purge all artifacts tagged with {{target_channel}}/my_product/latest when the project is promoted.
.expeditor/config.yml
---
subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - purge_packages_chef_io_fastly:{{target_channel}}/my_product/latest

trigger_pipeline

Trigger a new build on a Buildkite pipeline.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to any workload. For the project_promoted workload, this action supports both semantic version and “head of channel” promotion patterns.
Sample Usage
Trigger the omnibus/release Omnibus pipeline when a pull request is merged.
.expeditor/config.yml
---
pipelines:
  - omnibus/release

subscriptions:
  - workload: pull_request_merged:{{github_repo}}:{{release_branch}}:*
    actions:
      - trigger_pipeline:omnibus/release

unlock_staging_area

Unlock the staging area, allowing for new workloads to be executed.

Default Action Set Order
post-commit - this action is run after any commits have been made. Any modifications made to the git workspace will be ignored.
Composite Workload Support
This action will only act on the most recent workload in a composite workload
Retriable
Yes - this action can be retried if it fails.
Relevant Configuration
The behavior of this action is managed using the following Expeditor configuration:
Supported Workloads
This action can be executed in response to any workload. For the project_promoted workload, this action supports both semantic version and “head of channel” promotion patterns.
Sample Usage
Unlock the post_merge staging area when the habitat/build pipeline fails. We recommend checking out our staging area guide for more information.
.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_failed:{{agent_id}}:habitat/build:*
    actions:
      - unlock_staging_area:post_merge