Trigger Step

A trigger step creates a build on another pipeline. You can use trigger steps to separate your test and deploy pipelines, or to create build dependencies between pipelines. Trigger steps can only be defined in your pipeline.yml file.


All builds created by a trigger step will have the same author as the parent build. This user must:

  • be a member of your organization
  • have a verified email address

If you have Teams enabled in your organization, the authoring user must also have:

  • 'Build' permission on every pipeline that will be triggered

If the author does not have the required access, the build will fail, and builds on subsequent pipelines will not be triggered.

Trigger Step Attributes

Required attributes:

trigger The slug of the pipeline to create a build. The pipeline slug must be lowercase.
Example: "another-pipeline"

Optional attributes:

build An optional map of attributes for the triggered build.
label The label that will be displayed in the pipeline visualisation in Buildkite. Supports emoji.
Example: ":rocket: Deploy"
async If set to true the step will immediately continue, regardless of the success of the triggered build. If set to false the step will wait for the triggered build to complete and continue only if the triggered build passed. Default value: false
branches The branch pattern defining which branches will include this step in their builds.
Example: "master stable/*"
if A boolean expression to restrict the running of the step. See Using conditionals for supported expressions.
Example: build.message != "skip me"

Optional build attributes:

message The message for the build. Supports emoji. Default: the label of the trigger step.
Example: "Triggered build"
commit The commit hash for the build. Default: "HEAD"
Example: "ca82a6d"
branch The branch for the build.
Default: The triggered pipeline's default branch.
Example: "production"
meta_data A map of meta-data for the build.
Example: release-version: "1.1"
env A map of environment variables for the build.
Example: RAILS_ENV: "test"
- trigger: "data-generator"
  label: ":package: Generate data"
      release-version: "1.1"

Environment Variables

You can use environment variable substitution to set attribute values:

- trigger: "app-deploy"
  label: ":rocket: Deploy"
  branches: "master"
  async: true
    message: "${BUILDKITE_MESSAGE}"
    commit: "${BUILDKITE_COMMIT}"
    branch: "${BUILDKITE_BRANCH}"

To pass through pull request information to the triggered build, pass through the branch and pull request environment variables:

- trigger: "app-sub-pipeline"
  label: "Sub-pipeline"
    message: "${BUILDKITE_MESSAGE}"
    commit: "${BUILDKITE_COMMIT}"
    branch: "${BUILDKITE_BRANCH}"

To set environment variables on the build created by the trigger step, use the env attribute:

- trigger: "release-binaries"
  label: ":package: Release"