jobs.<job_id>.steps[*].if

Use jobs.<job_id>.steps[*].if to require a condition be met before a step is run. You can use any supported context and expression to create a conditional.

When you use expressions in an if conditional, you may omit the ${{ }} expression syntax because CloudBees platform automatically evaluates the if conditional as an expression. However, this rule does not apply everywhere.

You must use the ${{ }} expression syntax or escape with '', "", or () when the expression starts with !, since ! is reserved notation in YAML format.

Using the ${{ }} expression syntax turns the contents into a string, and strings are truthy. For example, if: true && ${{ false }} will evaluate to true.

Example usage: Contexts

A conditional at the job level cannot reference any step outputs. However, a conditional within a step can reference previous steps in the same job.

In the following example, the step only runs when the event type is a push and the branch is main.

steps:
  - name: My first step
    uses: docker://alpine:3.18
    if: ${{ cloudbees.event_name == 'push' && cloudbees.scm.ref == 'refs/heads/main' }}
    run: echo This event is a push on the main branch.▼

In the following example, the first step is referenced in the second step.

jobs:
  my-job:
    steps:
      - name: First step
        id: detect_build_type
        uses: docker://alpine:3.19
        run: |
          if [ '${{ cloudbees.scm.ref }}' = refs/heads/main ]; then
            echo true > $CLOUDBEES_OUTPUTS/is_release_build
          fi
      - name: Second step
        if: ${{ steps.detect_build_type.outputs.is_release_build }}
        uses: docker://alpine:3.19
        run: |
          echo Publish a release...▼

Example usage: Status checks

In the following example, my backup step only runs when the previous step of a job fails.

steps:
  - name: My first step
    uses: cloudbees/checkout@v1
  - name: My backup step
    if: ${{ failure() }}
    uses: cloudbees/kaniko@v1▼

Example usage: Using secrets

You cannot directly reference a secret in jobs.<job_id>.steps[*].if. CloudBees recommends setting secrets as environment variables at the job level, then referencing these environment variables in the conditional, as in the following example:

name: Check secret set status
on: push
jobs:
  my-job:
    env:
      my_secret: ${{ secrets.my_secret }}
    steps:
      - uses: docker://alpine:3.18
        if: ${{ env.my_secret != '' }}
        run: echo 'Step runs only if secret value is set.'
      - uses: docker://alpine:3.18
        if: ${{ env.my_secret == '' }}
        run: echo 'Step runs only if secret value is not set.'▼

If a secret is not set, the return value of an expression referencing the secret (such as ${{ secrets.my_secret }} is an empty string.