Build Pipelines series: How to conditionally run workflows in Bitrise Pipelines

Welcome back to our series on mastering Bitrise build pipelines. Today, we delve into a pivotal strategy for optimizing your CI/CD pipeline: conditionally running workflows within Bitrise. This capability allows for more efficient resource use, faster build times, and a more dynamic development process. Whether you're looking to run specific workflows only under certain conditions or aiming to streamline your deployment process, this post will guide you through configuring your pipeline for conditional workflow execution.

What to expect in this series:

• Blog post 1: How to share files with workflows in a pipeline on Bitrise
• Blog post 2: How to conditionally run workflows of a Bitrise pipeline (you are here)
• Blog post 3: How to configure your pipeline stages to save credits
• Blog post 4: How to run iOS tests in parallel

Why conditional workflow execution is essential

Efficiency and speed are paramount in CI/CD. However, not all workflows need to be executed under every circumstance. For example:

• Running a workflow only on Bitrise but not locally, and vice versa.
• Executing UI tests only when UI files have changed.
• Triggering the deployment workflow exclusively on the main branch.
• Adapting your pipeline to run workflows conditionally can significantly enhance your development process, saving time and resources.

When configuring a pipeline to have workflows running conditionally, examples developers benefit from include:

• Resource optimization: By running workflows only when necessary, you minimize the usage of computing resources. This is especially beneficial in cloud-based environments where resource usage directly impacts costs. You can avoid running tests or deployments for changes that don't affect certain parts of your system.
• Faster feedback loops: Conditional workflows can be designed to provide faster feedback on the changed aspects of the code. 
• Increased efficiency: Running only the relevant parts of your pipeline reduces the total execution time, making the development process more efficient. Developers can focus on resolving issues and integrating features without being bogged down by unnecessary waiting for irrelevant workflow steps to complete.

Configuring conditional workflows in Bitrise: A step-by-step guide

Step 1: Setting up your pipeline

Start by creating a pipeline with two stages, each containing two workflows. This forms the basic structure for implementing conditional execution.

‍

pipelines:
  our-awesome-pipeline:
    stages:
    - stage-1: {}
    - stage-2: {}
stages:
  stage-1:
    workflows:
    - my-workflow-1: {}
    - my-workflow-2: {}
  stage-2:
    workflows:
    - my-workflow-3: {}
    - my-workflow-4: {}
workflows:    
  my-workflow-1: {}
  my-workflow-2: {}
  my-workflow-3: {}
  my-workflow-4: {}

Step 2: Conditional workflow configuration

Now, configure my-workflow-2 to run only locally, and use the run_if condition in your stage configuration. This ensures thatmy-workflow-2 is skipped during CI environments on Bitrise, demonstrating how to selectively run workflows based on your operational environment.

stage-1:
  workflows:
  - my-workflow-1: {}
  - my-workflow-2:
      run_if: '{{ enveq "CI" "true" }}'

It should look like this:

To decide if my-workflow-4 should be executed or not, you can now set an environment variable in my-workflow-1. More on this below. 

Step 3: Environment variable utilization

Extend my-workflow-1 to set an environment variable that dictates whether my-workflow-4 should execute. This illustrates the dynamic decision-making within your pipeline based on workflow outcomes.

my-workflow-1:
  steps:
  - script@1:
      inputs:
      - content: |-
         envman add --key SHOULD_RUN_MY_WORKFLOW_4 --value false

Step 4: Sharing variables across pipelines

Incorporate the share-pipeline-variable Step to make the SHOULD_RUN_MY_WORKFLOW_4 variable accessible across the pipeline. This step maintains workflow interdependencies and decision logic throughout your pipeline.

my-workflow-1:
  steps:
  - script@1:
      inputs:
      - content: |-
         envman add --key SHOULD_RUN_MY_WORKFLOW_4 --value false
  - share-pipeline-variable@1:
      inputs:
      - variables: |-
          SHOULD_RUN_MY_WORKFLOW_4

Step 5: Applying conditional logic

Utilize the SHOULD_RUN_MY_WORKFLOW_4 in the stage configuration for my-workflow-4, completing the setup for conditional workflow execution. This facilitates the application of previously set conditions and manages your workflow execution effectively.

stage-2:
  workflows:
  - my-workflow-3: {}
  - my-workflow-4:
      run_if: '{{ enveq "SHOULD_RUN_MY_WORKFLOW_4" "true" }}'

E.g. since we set the env var as constant “false” in step 3, my-workflow-4 will now be skipped:

Note: In a real-world use-case, the value will be dynamically set to true or false depending on a decision made in my-workflow-1.

YML Configuration

---
format_version: '13'
default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git
project_type: android

pipelines:
  our-awesome-pipeline:
    stages:
    - stage-1: {}
    - stage-2: {}
    
stages:
  stage-1:
    workflows:
    - my-workflow-1: {}
    - my-workflow-2:
        run_if: '{{ enveq "CI" "true" }}'
  stage-2:
    workflows:
    - my-workflow-3: {}
    - my-workflow-4:
        run_if: '{{ enveq "SHOULD_RUN_MY_WORKFLOW_4" "true" }}'

workflows:
  my-workflow-1:
      steps:
      - script@1:
          inputs:
          - content: |-
             envman add --key SHOULD_RUN_MY_WORKFLOW_4 --value false
      - share-pipeline-variable@1:
          inputs:
          - variables: |-
              SHOULD_RUN_MY_WORKFLOW_4
  my-workflow-2: {}
  my-workflow-3: {}
  my-workflow-4: {}

meta:
  bitrise.io:
    stack: linux-docker-android-20.04
    machine_type_id: standard

Highlighted Bitrise Steps

• Pipeline’s stage configuration: Tailors workflow execution based on predefined conditions.
• share-pipeline-variable: Facilitates the sharing of environment variables across workflows for conditional logic.

Conclusion

Through this exploration of conditionally running workflows within Bitrise pipelines, we've uncovered techniques to enhance CI/CD pipeline efficiency. This approach free up your resources’s time and aligns workflow execution with your project's specific needs, ensuring that your development process is as efficient and effective as possible.

Looking forward to our next post, we will explore configuring pipeline stages to save credits on Bitrise, further optimizing your CI/CD strategy. 

Eager to implement these strategies? Visit Bitrise Pipelines documentation for more guides and tutorials. Not a Bitrise user? Start for free today.