Configuring a Bitrise Pipeline

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.

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.

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:

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:
    - script@1:
        title: Print secret1
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -ex            
            echo $secret1
    - script@1:
        title: Print all env vars
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -ex            
            printenv
    - script@1:
        title: Wait 20 seconds
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -ex
            sleep 20
  successful-30s:
    steps:
    - script@1:
        title: Wait 30 seconds
        inputs:
        - content: |-
            #!/usr/bin/env bash
            set -ex
            sleep 30

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.

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