Using Conditionals

The if parameter provides the ability to conditionally run steps. Using C-like expressions, boolean conditions are defined to restrict the running of steps to specific circumstances. Conditionals can be used in all YAML-based pipelines.

Use the if attribute in your pipeline's YAML 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.

Multi-line conditionals can be added with the | character:

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\//

Supported syntax

The below expressions are supported by the if attribute:

Comparators == != =~ !~
Logical operators || &&
Array operators includes
Integers 12345
Strings 'feature-branch' "feature-branch"
Booleans true false
Null null
Parentheses ( )
Regular expressions /^v1.0/
Prefixes !
Comments // This is a comment

Formatting regular expressions

When using regular expressions in conditionals, the regular expression must be on the right hand side, and the use of the $ anchor symbol must be escaped to avoid environment variable substitution. For example, to match branches ending in "/feature" the conditional statement would be build.branch =~ /\/feature$$/.

Supported variables

The below variables are supported by the if attribute:

build.author.email String The email address of the user who authored the build's commit
build.author.id String The ID of the user who authored the build's commit
build.author.name String The name of the user who authored the build's commit
build.author.teams Array An array of the team/s which the user who authored the build's commit is a member of
build.branch String The branch on which this build is created from
build.commit String The commit number of the commit the current build is based on
build.creator.email String The email of the user who created the build
build.creator.id String The ID of the user who created the build
build.creator.name String The name of the user who created the build
build.creator.teams Array An array of the team/s which the user who created the build is a member of
build.env() String, null This function returns the value of the environment passed as the first argument, otherwise null if the environment variable has not been set
build.id String The ID of the current build
build.message String, null The current build's message
build.number Integer The number of the current build
build.pull_request.base_branch String, null The base branch that the pull request is targeting, otherwise null if the branch is not a pull request
build.pull_request.id String, null The number of the pull request, otherwise null if the branch is not a pull request
build.pull_request.draft Boolean, null If the pull request is a draft, otherwise null if the branch is not a pull request or the provider doesn't support draft pull requests
build.pull_request.repository String, null The repository URL of the pull request, otherwise null if the branch is not a pull request
build.pull_request.repository.fork Boolean, null If the pull request comes from a forked repository, otherwise null if the branch is not a pull request
build.source String The source of the event that created the build
Available sources: ui, api, webhook, trigger_job, schedule
build.tag String, null The tag associated with the commit the current build is based on
pipeline.default_branch String, null The default branch of the pipeline the current build is from
pipeline.id String The ID of the pipeline the current build is from
pipeline.repository String, null The repository of the pipeline the current build is from
pipeline.slug String The slug of the pipeline the current build is from
organization.id String The ID of the organization the current build is running in
organization.slug String The slug of the organization the current build is running in

Using build.env() with custom environment variables

To access custom environment variables with the build.env() function, ensure that the YAML pipeline steps editor has been enabled in the Pipeline Settings menu.

Example expressions

To run only when the branch is master or production:

build.branch == "master" || 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 fuction
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 build creator is in the deploy team:

build.creator.teams includes "deploy"

To run only non-draft pull requests:

!build.pull_request.draft