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

2 minute read

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

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.

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.