Enabling or disabling a Step conditionally

Abstract

You can enable or disable a Step in any given Workflow, and you can also set conditions for Steps. You can do so, either on your own computer, with the Bitrise CLI or by using the bitrise.yml tab of the Workflow Editor.

You can enable or disable a Step in any given Workflow, and you can also set conditions for Steps. You can do it either on your own computer, with the Bitrise CLI or by using the bitrise.yml tab of the Workflow Editor.

We mostly use run_if expressions to do these things. Check out the examples for possible template expressions: Examples of run_if expressions.

You can also view the examples on GitHub: Template expression examples.

A `run_if` can be any valid Go template

A run_if can be any valid Go template, as long as it evaluates to true or false (or any of the String representation, for example True, t, yes or y are all considered to be true). If the template evaluates to true, the Step will run, otherwise it won’t.

An example run_if to check a custom Environment Variable:

run_if: |-
        {{enveq "CUSTOM_ENV_VAR_KEY" "test value to test against"}}

This run_if will skip the Step if the value of CUSTOM_ENV_VAR_KEY is not test value to test against.

Disabling a Step

If you do not want to remove a Step from your Workflow but you don’t want it to run, you can disable it, using a run_if expression.

Experimenting with Workflows

To experiment with different configurations for a Workflow, without removing or disabling Steps, we recommend cloning the Workflow. You can modify the cloned Workflow as much as you wish without changing anything in the original.

Open your app’s bitrise.yml file.
Find the Step that you want to disable.

Add run_if: false to it.

- script:
    run_if: false
    inputs:
    - content: |-
        #!/bin/bash
        echo "This will never run, because of run_if:false"

Running a Step only in a CI environment

Running a Step only in a CI environment means your build will skip that particular Step for local builds. Like disabling Steps, you can do this with a run_if expression. Use this to debug builds locally.

The `.IsCI` flag

Many Steps have this .IsCI flag set by default: for example, the Git Clone Step. However, you can change the run_if property of these Steps, too: just set it to run_if: true.

Enabling CI mode locally

CI mode can be enabled on your own Mac/PC by setting the CI environment to true (for example, run export CI=true in your Bash Terminal), or by running bitrise run with the --ci flag: bitrise --ci run ....

Open your app’s bitrise.yml file.
Find the Step that you want to disable.

Add run_if: .IsCI to it.

- script:
    run_if: .IsCI
    inputs:
    - content: |-
        #!/bin/bash
        echo "This will only ever run in a CI environment because run_if: IsCI"

Running a Step only if the build failed

It is possible to run a Step ONLY if the build failed before it got to that particular Step. In addition to run_if, you will need to use the is_always_run property as well.

Open your app’s bitrise.yml file.
Find the Step that you want to disable.
Add run_if: .IsBuildFailed to it.

Add is_always_run: true to it.

This enables the Step to run even if a previous Step failed.

- script:
    is_always_run: true
    run_if: .IsBuildFailed
    inputs:
    - content: |-
        #!/bin/bash
        echo "Build Failed!"

Ignoring a failed Step without failing the build

Usually, when a Step fails during a build, the built itself fails, too. This isn't the case with every Step, of course: both the Bitrise.io Cache:Pull and the Bitrise.io Cache:Push Steps can fail without failing the build. You can also configure any other Step to ensure their failure doesn't fail the build.

YAML mode only

You can't do this on the graphical UI of the Workflow Editor: you have to edit your app's bitrise.yml file.

Open your app on Bitrise.
Click the Workflows button on the main page.
Go to the bitrise.yml tab.
Find the Step you need.

Add the is_skippable flag to it and set it to true:

- script: 
    is_skippable: true 
    inputs: 
    - content: |- 
        # !/bin/bash 
        echo "Failing Step." 
        exit 1 
        # exit 1 would mark this step as Failed, but it won't break the Build 
        # because of the is_skippable: true flag / property

Examples of run_if expressions

There are many different ways of using a run_if expression. The following Workflow contains examples for most of them, with commented explanations. The expressions are used with Script Steps that, when successfully running, print what that the used expression was true.

All expressions are valid Go templates. To learn about Go templates, check out the documentation: Go template docs.

workflows:
  primary:
    steps:
    #
    # Check if an Environment Variable's value is equal to a given string
    - script:
        title: Run-If expression
        run_if: |-
          {{getenv "TEST_KEY" | eq "test value"}}
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # Use the enveq function to check if an Env Var's value is equal to a given string
    - script:
        title: Run-If expression
        run_if: '{{enveq "TEST_KEY" "test value"}}'
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # Check if a given Env Var is NOT empty
    - script:
        title: Run-If expression
        run_if: '{{getenv "TEST_KEY" | ne ""}}'
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # Check if two Env Vars have the same value
    - script:
        title: Run-If expression
        run_if: '{{getenv "TEST_KEY_1" | eq (getenv "TEST_KEY_2")}}'
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # Use the available expression data properties
    #  like IsCI (checks if the build runs in a CI environment) or IsBuildFailed (checks if the build has failed) directly
    - script:
        title: Run-If expression
        run_if: |-
          {{.IsCI}}
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # You don't have to wrap the expression in {{...}} if it's a simple
    # oneliner
    - script:
        title: Run-If expression
        run_if: $.IsCI
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # You can even remove the $ sign, it's optional in a simple
    # expression like this
    - script:
        title: Run-If expression
        run_if: .IsCI
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # If-Else condition, in this example the Step will run if the build runs in a CI environment
    - script:
        title: Run-If expression
        run_if: |-
          {{if .IsCI}}
          true
          {{else}}
          false
          {{end}}
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # You can use multiple conditions
    - script:
        title: CI and Not Failed
        run_if: |-
          {{.IsCI | and (not .IsBuildFailed)}}
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    #
    # Check if the build is a pull request or not
    - script:
        title: Only if NOT a pull request
        run_if: not .IsPR
        inputs:
        - content: |-
            #!/bin/bash
            echo "RunIf expression was true"
    - script:
        title: Only if it was a Pull Request
        run_if: .IsPR
        inputs:
        - content: |-
            #!/bin/bash
            echo "Pull Request ID: ${PULL_REQUEST_ID}"

In this section: