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