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.

A trigger step can be defined in your pipeline settings, or in your pipeline.yml file, by setting the trigger attribute to the the slug of the pipeline you want to trigger.

pipeline.yml
steps:
  - trigger: deploy-pipeline

Permissions

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, one of the following conditions must be met:

  • The authoring user must have 'Build' permission on every pipeline that will be triggered
  • The triggering build has no creator and no unblocker, and the source pipeline and the target pipeline share a team that can 'Build'

If neither condition is true, the build will fail, and builds on subsequent pipelines will not be triggered.

If using bot users (unregistered users who are not part of any team) to trigger pipelines, make sure you have shared team which has the build permission on parent and child pipelines.

If your triggering pipelines are started by an API call or a webhook, it might not be clear whether the triggering user has access to the triggered pipeline, which will cause your build to fail. To prevent that from happening, make sure that all of your GitHub user accounts that are triggering builds are connected to Buildkite accounts.

Trigger step attributes

Required attributes:

trigger The slug of the pipeline to create a build. You can find it in the URL of your pipeline, and it corresponds to the name of the pipeline, converted to kebab-case.
Example: "another-pipeline"

Optional attributes:

build An optional map of attributes for the triggered build. Available attributes: branch, commit, env, message, meta_data
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.

Note that when async is set to true, as long as the triggered build starts, the original pipeline will show that as successful. The original pipeline does not get updated after subsequent steps or after the triggered build completes.
Default: false

branches The branch pattern defining which branches will include this step in their builds.
Example: "main 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"
key A unique string to identify the trigger step.
Keys can not have the same pattern as a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).
Example: "trigger-deploy"
Alias: identifier
allow_dependency_failure Whether to continue to run this step if any of the steps named in the depends_on attribute fail.
Default: false
skip Whether to skip this step or not. Passing a string provides a reason for skipping this command. Passing an empty string is equivalent to false. Note: Skipped steps will be hidden in the pipeline view by default, but can be made visible by toggling the 'Skipped jobs' icon.
Example: true
Example: false
Example: "My reason"
soft_fail When true, failure of the triggered build will not cause the triggering build to 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"
pipeline.yml
- trigger: "data-generator"
  label: ":package: Generate data"
  build:
    meta_data:
      release-version: "1.1"

Environment variables

You can use environment variable substitution to set attribute values:

pipeline.yml
- trigger: "app-deploy"
  label: ":rocket: Deploy"
  branches: "main"
  async: true
  build:
    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:

pipeline.yml
- trigger: "app-sub-pipeline"
  label: "Sub-pipeline"
  build:
    message: "${BUILDKITE_MESSAGE}"
    commit: "${BUILDKITE_COMMIT}"
    branch: "${BUILDKITE_BRANCH}"
    env:
      BUILDKITE_PULL_REQUEST: "${BUILDKITE_PULL_REQUEST}"
      BUILDKITE_PULL_REQUEST_BASE_BRANCH: "${BUILDKITE_PULL_REQUEST_BASE_BRANCH}"
      BUILDKITE_PULL_REQUEST_REPO: "${BUILDKITE_PULL_REQUEST_REPO}"

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

pipeline.yml
- trigger: "release-binaries"
  label: ":package: Release"
  build:
    env:
      RELEASE_STREAM: "${RELEASE_STREAM:-stable}"

Triggering specific steps in a pipeline

While you cannot trigger only a specific step in a pipeline, you can use conditionals or dynamic pipelines to achieve a similar effect.

An example using conditionals might look like this:

In the target pipeline, to run the command step only if the build was triggered by a specific pipeline, you might use something like this:

pipeline.yml
steps:
    - command: ./scripts/tests.sh
      if: build.source == 'trigger_job' && build.env('BUILDKITE_TRIGGERED_FROM_BUILD_ID') == 'the_triggering_pipeline'

If you also want the command step to run when the build was not triggered by the specific pipeline, you might need to do the opposite, and set conditions on the steps that you don't want to run when the build is triggered:

pipeline.yml
steps:
    - command: ./scripts/tests.sh
      if: build.source != 'trigger_job'

Cancel intermediate builds from multiple triggers

When multiple pipeline builds (for instance, run from the same commit) trigger the build of another pipeline, you can enable the Cancel Intermediate Builds feature to allow only the newest build to run, thereby reducing unnecessary, duplicated pipeline builds.

For example, assume a scenario with three pipelines—Pipeline A, Pipeline B, and Pipeline C. A commit that runs Pipeline A triggers a build on Pipeline B. The same commit runs Pipeline C, which also triggers a build on Pipeline B.

When Cancel Intermediate Builds:

  • Is enabled, the build of Pipeline B, run by whichever pipeline it was triggered by first, is canceled and the newest triggered Pipeline B build would be allowed to run.

  • Is not enabled, Pipeline B will run twice, as it will be triggered by both Pipeline A and Pipeline C without cancellation.

Regardless of whether or not Cancel Intermediate Builds is enabled, if either Pipeline A or Pipeline C is manually canceled before their triggering steps have occurred, then the Pipeline B build triggered by its canceled pipeline will not run, and Pipeline B will only run once (triggered by the other, non-canceled pipeline).