Using conditionals

Conditionals in pipelines

You can have complete control over when to trigger pipeline builds by using conditional expressions to filter incoming webhooks. You need to define conditionals in the pipeline's Settings page for your repository provider to run builds only when expressions evaluate to true. For example, to run only when a pull request is targeting the main branch:

Pipeline-level build conditionals are evaluated before any other build trigger settings. If both a conditional and a branch filter are present, both filters must pass for a build to be created – first the pipeline-level limiting filter and then the conditional filter.

Conditionals are supported in Bitbucket, Bitbucket Server, GitHub, GitHub Enterprise, and GitLab (including GitLab Community and GitLab Enterprise). You can add a conditional on your pipeline's Settings page in the Buildkite interface or using the REST API.

Conditionals in steps

Use the if attribute in your step definition to conditionally run a step.

In the below example, the tests step will only be run if the build message does not contain the string "skip tests".

steps:
    - command: ./scripts/tests.sh
      label: tests
      if: build.message !~ /skip tests/

The if attribute can be used in any type of step, and with any of the supported expressions and parameters. However, it cannot be used at the same time as the branches attribute.

Be careful when defining conditionals within YAML. Many symbols have special meaning in YAML and will change the type of a value. You can avoid this by quoting your conditional as a string.

steps:
    - command: ./scripts/tests.sh
      label: tests
      if: "!build.pull_request.draft"

Multi-line conditionals can be added with the | character, and avoid the need for quotes:

steps:
    - command: ./scripts/tests.sh
      label: tests
      if: |
        // Don't when the message contains "skip tests"
        // Only run on feature branches
        build.message !~ /skip tests/ &&
          build.branch =~ /^feature\//

Since if conditions are evaluated at the time of the pipeline upload, it's not possible to use the if attribute to conditionally run a step based on the result of another step.

To run a step based on the result of another step, upload a new pipeline based on the if condition set up in the command step like in the example below:

steps:
  - label: "Validation check"
    command: ./scripts/validation_tests.sh
    key: "validation-check"
  - label: "Run regression only if validation check is passed"
    depends_on: "validation-check"
    command: |
      if [ $$(buildkite-agent step get "outcome" --step "validation-check") == "passed" ]; then
         cat <<- YAML | buildkite-agent pipeline upload
         steps:
           - label: "Run Regression"
             command: ./scripts/regression_tests.sh
      YAML
      fi

Conditional notifications

To trigger Build notifications only under certain conditions, use the same if syntax as in your Steps.

For example, the following email notification will only be triggered if the build passes:

notify:
  - email: "dev@acmeinc.com"
    if: build.state == "passed"

Note that conditional expressions on the build state are only available at the pipeline level. You can't use them at the step level.

Conditionals and the broken state

Jobs become broken when their configuration prevents them from running. This might be because their branch configuration doesn't match the build's branch, or because a conditional returned false. This is distinct from skipped jobs, which might happen if a newer build is started and build skipping is enabled. A rough explanation is that jobs break because of something inside the build and are skipped by something outside the build.

Variable and syntax reference

Evaluate expressions made up of boolean operators and variables.

Operator syntax

The following expressions are supported by the if attribute.

Variables

The following variables are supported by the if attribute. Note that you cannot use Build Meta-data in conditional expressions.

Example expressions

To run only when the branch is main or production:

build.branch == "main" || build.branch == "production"

To run only when the branch is not production:

build.branch != "production"

To run only when the branch starts with features/:

build.branch =~ /^features\//

To run only when the branch ends with /release-123, such as feature/release-123:

build.branch =~ /\/release-123\$/

To run only when building a tag:

build.tag != null

To run only when building a tag beginning with a v and ends with a .0, such as v1.0:

// Using the tag variable
build.tag =~ /^v[0-9]+\.0\$/

// Using the env function
build.env("BUILDKITE_TAG") =~ /^v[0-9]+\.0\$/

To run only if the message doesn't contain [skip tests], case insensitive:

build.message !~ /\[skip tests\]/i

To run only if the build was created from a schedule:

build.source == "schedule"

To run when the value of CUSTOM_ENVIRONMENT_VARIABLE is value:

build.env("CUSTOM_ENVIRONMENT_VARIABLE") == "value"

To run when the unverified build creator is in the deploy team:

build.creator.teams includes "deploy"

To run only non-draft pull requests:

!build.pull_request.draft