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 that omits the step when false. See Using conditionals for supported expressions.
Example: build.message != "skip me"
depends_on A list of step keys that this step depends on. This step will only run after the named steps have completed. See managing step dependencies for more information.
Example: "test-suite"
allow_dependency_failure Whether to continue to run this step if any of the steps named in the depends_on attribute fail.
Default: false

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"