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.

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 source pipeline and the target pipeline must 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 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. The pipeline slug must be lowercase.
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.
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
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"

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: "master"
  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}"