Actions

bash

For maximum flexibility, Expeditor can defer to local 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.

Expeditor supports the following script types:

  • bash
  • ruby

Expeditor will inject various credentials and environment variables into this container at runtime so you can perform the necessary operations against our various internal and external properties. For example, here are the activities that you can perform inside your scripts by default (no additional setup is necessary). To help avoid buffer overflow errors, if an environment variable value is larger than 10000 characters, Expeditor will trim that value to 10000 characters and append ... to the end. This is typically only an issue with values coming from Workloads, and should not impact the performance of Expeditor.

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

It is the recommended pattern to keep all your Expeditor scripts in the .expeditor folder along with the config.yml.

Example

merge_actions:
  - bash:.expeditor/update_version.sh
  - bash:.expeditor/update_dockerfile.sh

Supported Events

  • All Events

Available Accounts

To simplify your scripting, the following accounts are available via the appropriate methods.

  • Read access to Chef’s Vault instance to access necessary environment variables.
  • Interact with GitHub (via git and the GitHub API) as the chef-expeditor GitHub App.
  • Interact with the chef-cd and chef-es AWS accounts via the aws-cli.

Globally Available Environment Variables

Default access to these environment variables has been deprecated and will be removed in January 2020. Please shift to leveraging the new helpers/actions, or accessing the secret from Vault directly via the included vault CLI.

For more information on accessing workload values as environment variables, read here.

Helper Functions

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

add_delivery_remote

Add the delivery git remote to the workspace within the container. Necessary for submitting a delivery_review.

Parameters
  1. The name of your Chef Automate Workflow organization.
  2. The name of your Chef Automate Workflow project.
Example
add_delivery_remote products chef-server

approve_change

Approve a change_id generated by the delivery_review helper.

Parameters
  1. The name of your Chef Automate Workflow organization.
  2. The name of your Chef Automate Workflow project.
  3. The Change ID generated by delivery_review.
Example
change_id=$(delivery_review)
approve_change products chef-server ${change_id}

connect_to_acc

Configure the workspace to talk to automate.chef.co (ACC).

Parameters
None
Example
connect_to_acc

deliver_acceptance

Deliver the latest change in Acceptance for the given project.

Parameters
  1. The name of your Chef Automate Workflow organization.
  2. The name of your Chef Automate Workflow project.
Example
deliver_acceptance products chef-server

delivery_review

Submit a change to the Chef Automate Workflow project configured using add_delivery_remote.

Parameters
None
Example
touch tracker_file
echo $(date) >> tracker_file
git commit --message "Update Tracker file with $(date)"
change_id=$(delivery_review)

get_github_file

Get the contents of the given file directly from GitHub.

Parameters
  1. The repository (e.g. chef/chef-dk).
  2. The branch from which to download the file (e.g. master).
  3. The path, relative to the project root, where you wish to download the file.
Example
get_github_file chef/chef-dk master .expeditor/update_version.sh > /tmp/update_version.sh

open_pull_request

Open a pull request against the GitHub repository. This provides an alternative to commiting changes directly to master.

Parameters
  1. The base branch (defaults to master)
Example
# Check out a branch on which to perform the work
branch="expeditor/run-myscript"
git checkout -b "$branch"

# .. do some awesome stuff that tweaks files. Maybe a `bundle update`?

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

# Open the pull request
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"

post_slack_message

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

Parameters
  1. The name of the slack channel (no octothorp).
  2. The string contents of the message.
Example
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 Discourse

Parameters
  1. The title of the post.
  2. The string contents of the message.
Example
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 "random" "$MESSAGE"

wait_for_change_to_be_ready_to_approve

Wait until the given Change has passed Verify and is ready to be approved.

Parameters
  1. The name of your Chef Automate Workflow organization.
  2. The name of your Chef Automate Workflow project.
  3. The Change ID generated by delivery_review.
Example
change_id=$(delivery_review)
wait_for_change_to_be_ready_to_approve products chef-server ${change_id}

built_in:build_docker_image

When specified, Expeditor will run a Docker build in the context of the root of your repository using the Dockerfile specified via docker.dockerfile. It is intended to mirror the functionality of the Docker build service as closely as possible in anticipation for external support.

In the near future, rather than doing builds locally we will be shifting to triggering builds on the Docker Build service. This action will be replaced with a trigger_docker_image_build action.

Action Set Order
post-commit
Retriable
true
Relevant Configuration
Example
docker_images:
  - chef

subscriptions:
  - workload: artifact_published:unstable:chef:*
    actions:
      - built_in:build_docker_image

built_in:build_gem

When a pull request is merged, Expeditor will build the specified RubyGems and upload them to Artifactory.

Do not use this action for gems also built as part of their Omnibus package.
Action Set Order
post-commit
Retriable
true
Relevant Configuration
Example
rubygems:
  - ohai

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

built_in:bump_version

When a pull request is merged, Expeditor will bump the version in your github.version_file unless that file was modified as part of the pull request.

In the scenario where the github.version_file was not modified as part of the pull request, Expeditor will bump either the PATCH or MINOR version (depending on whether or not one of the labels specified in the github.minor_bump_labels is present). By default, the PATCH/BUILD version number in your github.version_file is bumped. If the pull request contains a label that is configured in github.minor_bump_labels, the MINOR version number will be bumped, and the PATCH/BUILD version number will be set to 0.

In the scenario where the github.version_file was modified as part of the pull request, the bump_version action will assume that you’ve modified the file to your liking and proceed with the action.

Once the “new version” value has been resolved, the action will create a git tag with the new version using the format specified in github.version_tag_format. You’ll want to ensure that your release branches will not duplicate the tags that are created. It is recommended that you limit one MAJOR version line per release branch (e.g. 13 on master, 12 on chef-12).

Action Set Order
pre-commit
Retriable
true
Example
github:
  version_file: 'VERSION'             # default
  version_tag_format: '{{version}}'   # default
  release_branch:
    - master                          # default

merge_actions:
  - built_in:bump_version

built_in:create_github_release

Create a GitHub release record for the current version. The product name used in the title of the release entry will be retrieved from the mixlib-install product matrix; the first product_key entry in the config will be used. The body of the release entry will be the current changelog content for the latest stable release.

Action Set Order
post-commit
Retriable
true
Supported Events
Relevant Configuration
Example
product_key: chef

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

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

built_in:github_auto_assign_author

Self-assign the author of the pull request.

Action Set Order
pre-commit
Retriable
true
Supported Events
Relevant Configuration
None
Example
subscriptions:
  - workload: pull_request_opened:{{agent_id}}:*
    actions:
      - built_in:github_auto_assign_author

built_in:noop

A simple built in that does nothing. It is used primarily for testing and documentation purposes.

Action Set Order
false
Retriable
true
Supported Events
  • All
Example
subscriptions:
  - workload: generic_workload_published:*
    actions:
      - noop:sample_action

built_in:notify_chefio_slack_channels

Notify a list of pre-determined Slack channels in the Chef Software, Inc. private Slack workspace that a particular event occurred. The channels notified, and the content of the message, depend on the event being responded to.

By default, the following Slack channels are notified:

  • The channel where the /expeditor promote was triggered
  • Slack channels that have subscribed to the event via the /expeditor subscribe
Action Set Order
post-commit
Retriable
true
Relevant Configuration
Example
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 received by Expeditor.

Action Set Order
post-commit
Retriable
true
Supported Events
Relevant Configuration
Example
beta:
  notify_http_endpoints:
    - http://example.org/some-endpoint

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 Artifactory instance to it’s next logical channel.

Action Set Order
post-commit
Retriable
true
Supported Events
Relevant Configuration
Example
product_key:
  - chef
  - angrychef

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

Current Limitations

  • This action only supports promoting from current to stable. If the artifact is not already in current, the action will fail.

built_in:promote_habitat_packages

Will promote the Habitat packages configured in your .bldr.toml to the appropriate channel.

In addition, if you specify the docker export target, it will also tag the associated docker image with the appropriate channel as well.

Action Set Order
post-commit
Retriable
true
Relevant Configuration
Example
pipelines:
  - build/habitat

promote:
  channels:
    - unstable
    - stable

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

built_in:publish_rubygems

For some Omnibus projects, when the deb or rpm is built a corresponding rubygem is also built and published to Chef’s internal Artifactory instance. This action will publish the specified version of the rubygem to rubygems.org.

Action Set Order
post-commit
Retriable
true
Relevant Configuration
Example
rubygems:
  - chef
  - chef-config

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.

Action Set Order
pre-commit
Retriable
true
Relevant Configuration
Example
github:
  changelog_file: 'CHANGELOG.md' # default

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

built_in:tag_docker_image

Tag the Docker image associated with the given version with the target channel and other version information. For example, when chef 13.2.5 is promoted to current, it will tag chef/chef:13.2.5 as chef/chef:current. Then, when it is promoted to stable, it will tag it as chef/chef:latest, chef/chef:13, and chef/chef:13.2.

Action Set Order
post-commit
Retriable
true
Supported Events
Relevant Configuration
Example
docker_images:
  - chef

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

built_in:update_changelog

When a pull request is merged on one of your release branches, Expeditor will update your changelog file (specified via github.changelog_file) with information from the pull request. See the changelog documentation for more information about how to setup your changelog.

Action Set Order
pre-commit
Retriable
true
Supported Events
Relevant Configuration
Examples
github:
  changelog_file: 'CHANGELOG.md' # default

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

post_github_comment

In response to a pull_request event, you can submit a comment to the Pull Request in question. This is useful for things like first-response comments. You have all the variables listed under pull_request on the Workloads reference page available to you.

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

promote

In most cases, the promotion should be triggered manually using the promote Slack Command. However, there are some cases where the promotion might be an action triggered by another workload such as a schedule. In that case, you can use the promote action.

Action Set Order
post-commit
Retriable
true
Supported Events
  • All events
Relevant Configuration
Example
schedules:
  - name: morning_promotion
    description: Automatically promote every morning
    cronline: "0 8 * * *"

promote:
  channels:
    - unstable
    - current
    - stable

subscriptions:
  # Automatically promote unstable to current every morning
  - workload: schedule_triggered:{{agent_id}}:morning_promotion:*
    actions:
      - promote:chef/example:master:unstable

purge_packages_chef_io_fastly

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

The identifier portion of the action definition supports Mustache settings for all Workload metadata values (see example below).

Action Set Order
post-commit
Retriable
true
Supported Events
  • All events
Relevant Configuration
None
Example
subscriptions:
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - purge_packages_chef_io_fastly:{{target_channel}}/my_product/latest

trigger_pipeline

The trigger_pipeline action allows you to create a new Buildkite build.

Action Set Order
post-commit
Retriable
true
Supported Events
  • All events
Relevant Configuration
Example
pipelines:
  - deploy/dev
  - deploy/production
  - omnibus/release

subscriptions:
  - workload: pull_request_merged:{{agent_id}}:*
    actions:
      - trigger_pipeline:deploy/dev
      - trigger_pipeline:omnibus/release
  - workload: project_promoted:{{agent_id}}:*
    actions:
      - trigger_pipeline:deploy/production

unlock_staging_area

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

Action Set Order
post-commit
Retriable
true
Supported Events
  • All
Relevant Configuration