Skip to main content

Configuring a Bitrise Pipeline

Currently, configuring a Pipeline is only possible by directly editing the bitrise.yml file. You can create and modify Workflows in the graphical Workflow Editor but you need to define Pipelines and Stages in YAML format.

Defining Pipelines, Steps, and Workflows

The bitrise.yml file contains the full configuration of your Pipelines. As with all bitrise.yml files, first you need to define the format version and the project type.

---
format_version: '8'
default_step_lib_source: 
project_type: android

This is a bare minimum bitrise.yml configuration. To define your Pipelines, you will need to use the pipelines attribute.

pipelines:  
  pipeline-successful:
    stages:
    - stage-successful-1: {}
    - stage-successful-2: {}
    - stage-successful-3: {}

In this example, we have a Pipeline called pipeline-successful, with three Stages that will run consecutively. This means that if stage-successful-1 finishes successfully, stage-successful-2 starts. If any of the Stages fail, the subsequent Stage will not start: instead, the Pipeline will be aborted and marked as failed.

Each Stage has to be defined separately under the stages attribute. Defining a Stage means specifying the Workflows that are part of the Stage.

stages:
  stage-successful-1:
    workflows:
    - test-1: {}
  stage-successful-2:
    workflows:
    - build-1: {}
    - build-2: {}
  stage-successful-3:
    workflows:
    - deploy-1: {}
    - deploy-2: {}

In this example, the Stages run the test-1, build-1, build-2, deploy-1, and deploy-2 Workflows.

Configuring Pipeline triggers

To set up automatic build triggers, you need a trigger map. The trigger map defines what code events should trigger builds. In a Pipeline configuration, you need to specify the Pipeline that should be triggered by certain code events, such as pushes, pull requests and tags.

Configuring Pipeline triggers using the Workflow Editor

This example focuses on configuring Pipeline triggers in YAML, but you can also set up Pipeline triggers in the Workflow Editor, as described here: Triggering builds automatically.

trigger_map:
- type: push
  push_branch: "pipe"
  pipeline: pipeline-successful

In this example, a code push to the pipe branch of the project’s repository triggers the pipeline-successful Pipeline. In a similar way, you can configure triggers for any code events: you just have to specify the code event, the branch or tag name, and the respective Pipeline.

You can find all available options for build triggers here: Build triggers in the configuration YAML.

Configuring a Stage to always run

By default, if a Stage fails - because one of its Workflows failed -, any other subsequent Stages of the Pipeline will not run. However, you can configure your Pipeline to run certain Stages unless the Pipeline is aborted.

To do so, you just need to set the should_always_run attribute of the Stage to true:

stages:
  stage-always-run-successful-1:
    should_always_run: true
    workflows:
    - deploy-1: {}
    - deploy-2: {}

In the example above, the Stage called stage-always-run-successful-1 will always run, regardless of the status of previous Stages. The only way these Stages will not run is if the Pipeline build is aborted by the user.

Aborting the Workflows of a failed Stage

By default, if a Workflow in a particular Stage fails, the other Workflows in the same Stage aren’t automatically aborted: these Workflows will run but the next Stage won’t start. However, you can change this behavior to immediately and automatically abort all other Workflows in the same Stage.

To do so, you need to set the abort_on_fail attribute to true:

stages:
  stage-abort-on-fail-1:
    abort_on_fail: true
    workflows:
    - deploy-1: {}
    - deploy-2: {}

Using artifacts from different Stages

You might have Workflows that rely on artifacts generated by Workflows in previous Stages. To be able to use them during your subsequent Workflows, you must:

  1. Specify files to share between Stages.

  2. Use the Pull Pipeline intermediate files Step.

Sharing Env Vars between Pipeline Stages

You can share Env Vars using a dedicated Step: Share Pipeline variables. For more information, see Sharing Env Vars between Pipeline Stages.

Specifying files to share between Stages

You can use the Deploy to Bitrise.io - Apps, Logs, Artifacts Step to push files and directories as intermediate files intended to be used by subsequent Workflows. To do so:

  1. Add the Deploy to Bitrise.io - Apps, Logs, Artifacts Step to your Workflow (typically to the end of the Workflow) that generates a build artifact.

        steps:
    ...
    - deploy-to-bitrise-io@2: {}

  2. Configure the Step’s Files to share between pipeline stages input under the Pipeline Intermediate File Sharing category.

    pipeline_share_example.png

When you are configuring the Files to share between pipeline stages input, the value you add must be a newline-separated list of colon-separated items using the following structure:

<file_or_directory_path>:<environment_variable_key>

  • file_or_directory_path: is the local file path of the file or directory you want to share with subsequent Stage Workflows.

    Sharing directories

    Directories are archived and uploaded as a single file, but the Pull Pipeline intermediate files Step will extract such archives automatically.

  • environment_variable_key: is the environment variable key to be assigned to the given item. This environment variable will hold the local file path of the item after downloaded by the Pull Pipeline intermediate files Step.

    Using environment variable keys

    You don't have to use the default environment variable keys, in fact you can assign any custom environment variable key you want.

    For example, "$BITRISE_IPA_PATH:BITRISE_APP_STORE_IPA_PATH"

    If you want to use the default environment variable keys, you can use a shorthand syntax.

    For example, you can use "BITRISE_TEST_BUNDLE_PATH" instead of "$BITRISE_TEST_BUNDLE_PATH:BITRISE_TEST_BUNDLE_PATH"

Let's look at an example!

If you would like to share the directory which contains the build test files ($BITRISE_TEST_BUNDLE_PATH) generated by the xcode-build-for-test Step and keep its default key, and the IPA file ($BITRISE_IPA_PATH) generated by the xcode-archive Step and assign a custom environment variable key, you would need to use the following structure:

    steps:
    ...
    - deploy-to-bitrise-io@2:
        inputs:
        - pipeline_intermediate_files: |-
            BITRISE_TEST_BUNDLE_PATH
            $BITRISE_IPA_PATH:BITRISE_APP_STORE_IPA_PATH

Using the Pull Pipeline intermediate files Step

If you have Workflows, which require access to artifacts generated by Workflows in previous Stages, you can use the Pull Pipeline intermediate files Step:

  1. Add the Pull Pipeline intermediate files Step to your Workflow (typically at the beginning of the Workflow, or before any Step that would rely on the shared files):

    steps:
  - pull-intermediate-files@1: {}

  2. Use the artifact_sources input to specify a set of Stages and Workflows. The input’s syntax is: {stage-name}.{workflow-name}:

    steps:
  - pull-intermediate-files@1:
      inputs:
        - artifact_sources: stage-1\..*

    In the example above, we’re pulling all artifacts from all Workflows in the Stage called stage-1.

    Setting specific Workflows and using wildcards

    You can set specific Workflows to pull artifacts from them or use wildcards in other ways:

    • stage1.workflow1 - Gets the artifacts from the stage1's workflow1.

    • stage1\..* - Gets all artifacts from the stage1's Workflows.

    • .*\.workflow1 - Gets workflow1s' artifacts from all Stages.

    • .* - Gets every generated artifact in the Pipeline.

  3. When the Step finishes, your files and directories specified via the Deploy to Bitrise.io - Apps, Logs, Artifacts Step should now be restored.

For more information and details, check out the Step repository.

Sharing Env Vars between Pipeline Stages

You can reuse any environment variable from a Workflow and reuse it in subsequent Stages using the Share Pipeline variablesStep.

Optional Workflows using run_if conditions

You can easily combine the Share Pipeline variables Step with run_if expressions to create Pipelines with optional Workflows. For more information, check out Setting up run_if conditions for optional Workflows using Pipelines.

To do so:

  1. Add the Share Pipeline variables Step to the Workflow.

  2. Optionally, you can define additional run conditions in the Additional run conditions input. The Step will only run if the conditions you specify here are true.

  3. Add the Env Var(s) you would like to use in subsequent Stages in the Variables to share between Pipeline Stages input.

    Using environment variable keys

    You can define Env Vars using a {key}={value} syntax. For example, MY_ENV_KEY=value, or INSTALL_PAGE_URL=$BITRISE_PUBLIC_PAGE_URL.

    If you want to use the default environment variable keys, you can use a shorthand syntax. For example, EXISTING_ENV_KEY.

    Sharing Env Vars using this Step does not override existing Env Vars defined in the app.

That's it! You can now use the Env Var in any subsequent Stage!

Setting up run_if conditions for optional Workflows using Pipelines

Optional Workflows is a Pipeline feature that allows you to decide if a Workflow should run or not based on conditions you set in a run_if expression.

Just like other Pipeline features, this feature is only available through the bitrise.yml.

In the bitrise.yml, under the stages/workflows field, you can add a run_if expression to any Workflow, and if they are part of a Pipeline build, the run_if will be evaluated to determine if the Workflow should run or not.

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 Workflow will run, otherwise it won’t.

Example 1. Pipeline example for run_if expressions

The following example demonstrates how to set up run_if expressions in the bitrise.yml file:

format_version: '11'
envs:
  FOO: 'BAR'
pipelines:
  pipeline1:
    stages:
    - stage1: {}
stages:
  stage1:
    workflows:
    - workflow-never-run:
        run_if: '{{ false }}'
    - workflow-always-run:
        run_if: '{{ true }}'
    - workflow-optionally-dont-run:
        run_if: '{{ getenv "FOO" | eq "notBAR" }}'
    - workflow-optionally-run:
        run_if: '{{ getenv "FOO" | eq "BAR" }}'
workflows:
  workflow-never-run: {}
  workflow-always-run: {}
  workflow-optionally-dont-run: {}
  workflow-optionally-run: {}

In this section:

A Bitrise Pipeline is the top level of the Bitrise CI/CD configuration. Pipelines can be used to organize the entire CI/CD process and to set up advanced configurations with multiple different tasks running parallel and/or sequentially.

The bitrise.yml file stores your entire build configuration for an app. It specifies your stack and the build triggers, and defines the Workflows of the app. When you make changes on the graphical UI of our Workflow Editor, you actually modify the bitrise.yml file.

A Workflow is a collection of Steps, Environment Variables, and other configurations. When Bitrise starts a build, it runs one or more Workflows according to the configuration defined in the bitrise.yml file.

A Stage is a collection of Workflows. Stages are the top-level building blocks of Pipelines. A Stage can contain multiple Workflows, which all run in parallel in the same Stage. If all Workflows are successful in a Stage, the Pipeline moves on to the next Stage. If any of the Workflows fail, the Pipeline ends without running the other Stages unless you configure a given Stage to always run.

A Step is a block of script execution that encapsulates a build task on Bitrise: the code to perform that task, the inputs and parameters you can define for the task, and the outputs the task generates.

app