<commit_before># Using Conditionals

Using conditionals, you can run builds or steps only when specific conditions are met. Define boolean conditions using C-like expressions. Note that you cannot use [Build Meta-data](/docs/pipelines/build-meta-data) in conditional expressions.

You can define conditionals at the step level in your `pipeline.yml` or at the pipeline level in your Buildkite version control provider settings.

{:toc}

## Conditionals in Pipelines

Define conditionals in the _Pipeline Settings_ for your repository provider to run builds only when expressions evaluate to `true`. For example, to run only when a branch is tagged `Approved`:

<%= image "conditionals.png", width: 864, height: 298, alt: "Conditional Filtering settings" %>

Conditionals are supported in [Bitbucket](/docs/integrations/bitbucket), [Bitbucket Server](/docs/integrations/bitbucket-server), [GitHub](/docs/integrations/github), [GitHub Enterprise](/docs/integrations/github-enterprise), and [GitLab](/docs/integrations/gitlab) (including GitLab Community and GitLab Enterprise).

<div class="Docs__note">
  <h3>Evaluating conditionals</h3>
  <p>Conditional expressions are evaluated at pipeline upload, not at step runtime.</p>
</div>

## 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".

```yml
steps:
	- command: ./scripts/tests.sh
	  label: tests
	  if: build.message !~ /skip tests/
```
{: codeblock-file="pipeline.yml"}

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.

```yml
steps:
	- command: ./scripts/tests.sh
	  label: tests
	  if: "!build.pull_request.draft"
```
{: codeblock-file="pipeline.yml"}

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

```yml
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\//
```
{: codeblock-file="pipeline.yml"}

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](/docs/pipelines/command-step) like in the example below:

```yml
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
{: codeblock-file="pipeline.yml"}

## Supported syntax

The below expressions are supported by the `if` attribute:

 <table>
 	<tbody><commit_msg>Fix the codeblock error I introduced<commit_after># Using Conditionals

Using conditionals, you can run builds or steps only when specific conditions are met. Define boolean conditions using C-like expressions. Note that you cannot use [Build Meta-data](/docs/pipelines/build-meta-data) in conditional expressions.

You can define conditionals at the step level in your `pipeline.yml` or at the pipeline level in your Buildkite version control provider settings.

{:toc}

## Conditionals in Pipelines

Define conditionals in the _Pipeline Settings_ for your repository provider to run builds only when expressions evaluate to `true`. For example, to run only when a branch is tagged `Approved`:

<%= image "conditionals.png", width: 864, height: 298, alt: "Conditional Filtering settings" %>

Conditionals are supported in [Bitbucket](/docs/integrations/bitbucket), [Bitbucket Server](/docs/integrations/bitbucket-server), [GitHub](/docs/integrations/github), [GitHub Enterprise](/docs/integrations/github-enterprise), and [GitLab](/docs/integrations/gitlab) (including GitLab Community and GitLab Enterprise).

<div class="Docs__note">
  <h3>Evaluating conditionals</h3>
  <p>Conditional expressions are evaluated at pipeline upload, not at step runtime.</p>
</div>

## 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".

```yml
steps:
	- command: ./scripts/tests.sh
	  label: tests
	  if: build.message !~ /skip tests/
```
{: codeblock-file="pipeline.yml"}

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.

```yml
steps:
	- command: ./scripts/tests.sh
	  label: tests
	  if: "!build.pull_request.draft"
```
{: codeblock-file="pipeline.yml"}

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

```yml
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\//
```
{: codeblock-file="pipeline.yml"}

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](/docs/pipelines/command-step) like in the example below:

```yml
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
```
{: codeblock-file="pipeline.yml"}

## Supported syntax

The below expressions are supported by the `if` attribute:

 <table>
 	<tbody>
{'fraction_non_alphanumeric': 0.09751596877217886, 'fraction_numerical': 0.00227111426543648, 'mean_word_length': 3.816131237183869, 'pattern_counts': {'":': 0, '<': 25, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '505886', 'n_tokens_mistral': 2031, 'n_tokens_neox': 1931, 'n_words': 842}