Configuring a Bitrise Pipeline

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 using bitrise.yml, but the same configuration can be achieved from the Workflow Editor's Triggers tab.

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

In this example, a code push to the pipe branch of the app’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 use the following attributes:

push_branch: A code push to the specified branch triggers the specified Pipeline.
pull_request_source_branch: A pull request opened from the specified branch triggers the specified Pipeline.
tag: A commit with the specified tag on it triggers the specified Pipeline.

Here’s an example of a fully configured Pipeline, including a trigger map:

---
format_version: '11'
default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git
project_type: android
trigger_map:
- push_branch: "*"
  pipeline: pipeline-successful
pipelines:
  pipeline-successful:
    stages:
    - stage-successful-1: {}
    - stage-successful-2: {}
    - stage-successful-3: {}
stages:
  stage-successful-1:
    workflows:
    - successful-20s: {}
  stage-successful-2:
    workflows:
    - successful-20s: {}
    - successful-30s: {}
  stage-successful-3:
    workflows:
    - successful-30s: {}
    - successful-20s: {}
workflows:
  successful-20s:
    steps:
    - [email protected]:
        title: Print secret1
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -ex            
            echo $secret1
    - [email protected]:
        title: Print all env vars
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -ex            
            printenv
    - [email protected]:
        title: Wait 20 seconds
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -ex
            sleep 20
  successful-30s:
    steps:
    - [email protected]:
        title: Wait 30 seconds
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -ex
            sleep 30

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 no matter what.

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 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:

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:

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:
    ...
    - [email protected]: {}
```
Configure the Step’s Files to share between pipeline stages input under the Pipeline Intermediate File Sharing category.

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"

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 the the IPA file ($BITRISE_IPA_PATH) generated by the xcode-archive Step, you would need to use the following structure:

    steps:
    ...
    - [email protected]:
        inputs:
        - pipeline_intermediate_files: |-
            "$BITRISE_TEST_BUNDLE_PATH:BITRISE_TEST_BUNDLE_PATH"
            "$BITRISE_IPA_PATH:BITRISE_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:

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:
  - [email protected]: {}
```
Use the artifact_sources input to specify a set of Stages and Workflows. The input’s syntax is: {stage-name}.{workflow-name}:
```
steps:
  - [email protected]:
      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.
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 share Env Vars between Stages by creating an artifact with the help of a Script Step and sharing that artifact as a Pipeline intermediate file. For more information, check out Using artifacts from different Stages.

Here is a bitrise.yml example:

pipelines:
  share_env_vars:
    stages:
    - pub: {}
    - sub: {}
stages:
  pub:
    workflows:
    - share_env_var_publish: {}
  sub:    
    workflows:
    - share_env_var_receive: {}
workflows:
  share_env_var_publish:
    steps:
    - [email protected]:
        inputs:
        - content: |
            #!/usr/bin/env bash
            set -e
            set -x
            touch vars.txt
            echo "FIRST=1" >> vars.txt
            echo "SECOND=2" >> vars.txt
        title: Make Env Var File
    - [email protected]:
        inputs:
        - pipeline_intermediate_files: vars.txt:ENV_VARS_FILEPATH
  share_env_var_receive:
    steps:
    - [email protected]: {}
    - [email protected]:
        inputs:
        - content: |
            #!/usr/bin/env bash
            set -e
            set -x
            while IFS='=' read -r k v; do
              envman add --key k --value $v
            done < "$ENV_VARS_FILEPATH"