Trigger step

Permissions

Builds created by a trigger step inherit ownership details from the parent build. Buildkite Pipelines uses these details to identify a user and determine whether the trigger is allowed.

If a user unblocks a preceding block step or submits an input step, Pipelines identifies the most recent unblocker or submitter as the creator. Otherwise, Pipelines uses the creator of the parent build.

For parent builds created by GitHub push webhooks, the creator depends on your organization's build creator semantics:

• With strict build creator semantics, Pipelines identifies the authenticated webhook sender through their connected GitHub account.
• Without strict build creator semantics, Pipelines first uses the commit author information in the webhook payload to identify a Buildkite user. The commit author's email must match a verified email on the Buildkite account. If no verified email matches, Pipelines tries to identify the webhook sender through their connected GitHub account.

When Pipelines identifies a creator, it checks that user's permissions when a trigger step runs. If Pipelines cannot identify a creator and Teams is enabled, the trigger step can use the shared-team permissions described below.

If you have Teams enabled in your organization, one of the following conditions must be met:

• The identified user must be a member of your organization and have Build permission on every target pipeline.
• The triggering build has no creator and no unblocker, and the source pipeline and the target pipeline share a team with Build permission.

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

Without strict build creator semantics, adding a verified commit-author email can change authorization from the shared-team fallback to the identified user's permissions. To keep permission checks consistent, give identified commit authors Build permission on every target pipeline. With strict build creator semantics, give the authenticated webhook sender this permission. If a user unblocks a preceding block step or submits an input step, give that user this permission. For builds without an identified creator, make sure the source and target pipelines share a team with Build permission.

Trigger step attributes

Required attributes:

Optional attributes:

Optional build attributes:

- trigger: "data-generator"
  label: ":package: Generate data"
  build:
    meta_data:
      release-version: "1.1"

Example: triggering parallel builds

steps:
  - trigger: "data-generator"
    label: ":package: Generate data"
    parallelism: 3
    build:
      meta_data:
        release-version: "1.1"

This creates three builds on the data-generator pipeline, each with a different BUILDKITE_PARALLEL_JOB value (0, 1, 2).

Agent-applied attributes

These attributes are only applied by the Buildkite agent when uploading a pipeline (buildkite-agent pipeline upload), since they require direct access to your code or repository to process correctly.

if_changed

For an example pipeline, demonstrating various forms of if_changed, see Using if_changed.

Environment variables

You can use environment variable substitution to set attribute values:

- 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:

- 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:

- 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:

• Testing for BUILDKITE_SOURCE =='trigger_job' to find out if the build was triggered by a trigger step
• Testing for BUILDKITE_TRIGGERED_FROM_BUILD_PIPELINE_SLUG to find out which pipeline triggered the build
• Custom environment variables passed to the triggered build

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:

steps:
    - command: ./scripts/tests.sh
      if: build.source == 'trigger_job' && build.env('BUILDKITE_TRIGGERED_FROM_BUILD_PIPELINE_SLUG') == '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:

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

Canceling intermediate builds and triggers

When using trigger steps that target pipelines with Cancel Intermediate Builds setting enabled, it's important to understand how this feature interacts with triggered builds. If a triggered build is "canceled" due to the Cancel Intermediate Builds setting being enabled, such trigger step will be marked as "skipped" in the triggering build.

Multiple triggered builds for the same pipeline

When multiple pipeline builds (for instance, when multiple builds are running as a result of a single commit) trigger builds in other pipelines, 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).