Using Conditionals
The if parameter provides the ability to run steps only when specific conditions are met. Using C-like expressions, boolean conditions are defined to restrict the running of steps to specific circumstances. Note that we do not support Build Meta-data for conditionals.
On this page:
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\//
Supported syntax
The below expressions are supported by the if attribute:
| Comparators | == != =~ !~ |
| Logical operators | || && |
| Array operators | includes |
| Integers | 12345 |
| Strings | 'feature-branch' "feature-branch" |
| Literals | true false 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.labels |
Array |
An array of label names attached to the pull request |
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