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

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.