Configuration YAML reference

Required: A configuration YAML file is invalid without it.

The version of the Bitrise configuration format.

The Bitrise CLI checks it to ensure compatibility between the configuration file and the CLI version. This is relevant for locally run builds: on the Bitrise website, the CLI is always up to date, so the format_version property doesn't have an effect on builds triggered.

format_version: '25'

The default Step library for the Steps used in your configuration. Bitrise uses this source if no specific source is provided for a given Step.

The default value is https://github.com/bitrise-io/bitrise-steplib.git. You can use your own fork of this repository as a Step source, or you can refer to Steps by including their exact source repository: Step reference/ID format.

default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git

The type of your Bitrise project, such as ios, android, flutter, and so on.

The project type can be modified at any point but after the initial setup, it has no relevance.

default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git

The title of the Bitrise configuration.

title: My Bitrise project

A short summary of the Bitrise configuration.

summary: This project runs tests for my app.

A detailed description of the Bitrise configuration.

description: This project runs unit and UI tests when a pull request is opened to the dev branch.

Docker container definitions used by Steps as service containers on Linux hosts.

One or more service can be configured for a group of Steps, allowing running Docker containers as services for advanced integration testing. These are tied to the lifecycle of a with group and will run alongside it in the background. When all Steps within the groups finish, they are cleaned up.

You need to define:

Read more: Service containers.

services:
 postgres:
   image: postgres:16
   envs: 
   - POSTGRES_USER: postgres
   - POSTGRES_DB: bitrise 
   ports:
   - 5432:5432 
   options: >-
     --health-cmd pg_isready
     --health-interval 10s
     --health-timeout 5s
     --health-retries 5
 redis: 
   image: redis:7
     ports: - 6379:6379
     options: >-
     --health-cmd "redis-cli ping"
     --health-interval 10s
     --health-timeout 5s
     --health-retries 5

Docker container definitions used by Steps as execution containers.

Docker containers can be defined for any Bitrise project in the configuration YAML file. You define the container in the top level of the configuration file and then refer to it in a with group in the Workflow configuration. You need to define:

Read more: Step execution containers.

containers:
  node-21:
    image: node:21.6

This property contains project-level configuration information, such as Environment Variables.

Meta information such as the build stack doesn't belong here but to the meta property.

app:
  envs:
  - TEST: '' 
    opts:
      is_expand: false

Stores project metadata key-value pairs related to the Bitrise configuration. Most importantly, it defines the default stack and the build machine type for the project.

Read more: Setting the stack in the Configuration YAML.

meta:
  bitrise.io:
    stack: linux-docker-android-22.04
    machine_type_id: g2.linux.2medium

Defines the build triggers on a project level. This is the legacy method of configuring triggers: we recommend using target-based triggers defined within a Pipeline or a Workflow instead.

Read more: Legacy project-based triggers.

trigger_map:
- pull_request_source_branch: "*"
  type: pull_request
  workflow: primary

Define Pipelines in your project's 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.

pipelines reference: Pipeline level properties.

Read more: About Pipelines.

pipelines:
  test:
  title: Test Pipeline
  summary: This Pipeline runs unit tests.
  workflows:
    primary: {}

The Workflows included in your configuration. A Workflow is a collection of Steps: reusable, configurable units of work. Steps are executed sequentially within a Workflow.

workflows reference: Workflow level properties.

workflows: 
  primary:
    steps: 
    - script: {}

Step bundles allow you to group multiple Steps into a single unit. With Step bundles, you can reuse Steps and sequences of Steps.

You can insert Step bundles into any Workflow. Unlike utility Workflows and Workflow chaining, Step Bundles can be placed anywhere in a Workflow.

Read more: Step bundles.

step_bundles:
  primary:
    steps:
    - git-clone: {}
    - restore-cache: {}

The include property allows you to use other configuration YAML files in your Bitrise configuration, to break down large, complex YAML files into smaller, modular components.

A modular YAML configuration includes:

Read more: Modular YAML configuration.

include:
  - path: path/to/config_module.yml

Tool version to set up. The version syntax supports:

Read more: Configuring tool versions.

tools:
  nodejs: 22:installed
  ruby: 3.3:latest

The title of the Pipeline.

This is not the same as the ID of the Pipeline: you set the ID when creating the Pipeline. Unlike the ID, the title does not have to be unique. It appears on the Workflow Editor UI in the Pipelines section: if you open the Pipeline selector dropdown menu.

pipelines:
  test:
    title: Test pipeline

A short summary of the Pipeline. Optional.

pipelines:
  test:
    summary: This Pipeline runs unit tests.

A detailed description of the Pipeline. Optional.

pipelines:
  test:
    description: 'This Pipeline runs unit tests in parallel, using test sharding.'

Target-based triggers defined for the Pipeline: if a code event matches the condition defined in a trigger, Bitrise will trigger a build with the Pipeline.

For the detailed syntax of the triggers property and its available options, check out:

Read more: YAML syntax for build triggers.

pipelines:
  test:
    triggers:
      push:
      - branch: main

The name that will appear on the status report sent to connected services (like GitHub, GitLab, Bitbucket, and so on) after the build is finished.

It can have both static and dynamic values, as well as combine the two types.

Supported characters and variables:

pipelines:
  test:
    status_report_name: ci/bitrise/510526/push

The Workflows that are part of the Pipeline configuration.

You can create dependencies between Workflows with the depends_on property.

pipelines:
  test:
    workflows:
      primary:

The priority setting determines the position of the Pipeline build in the build queue: the higher the priority, the sooner the Pipeline build will run.

Supported values:

Read more:

pipelines:
  test:
    priority: 10

This property defines the Workflows that this Workflow depends on. If any of the Workflows in the list fails, this Workflow won't run.

You can use both types of YAML array syntax to list dependant Workflows: block sequence and flow sequence. Any Workflow appearing in the dependency list must be part of the same Pipeline.

Supported values: Workflow names with YAML array syntax.

Read more: Creating a Pipeline.

pipelines:
  example:
    workflows:
      A: {}
      B:
        depends_on:
        - A
      C:
        depends_on:
        - A
      D:
        depends_on:
        - B
        - C

D:
  depends_on: [B, C]

When this property is true, the Pipeline and any other running Workflows are aborted if this Workflow fails.

Supported values: boolean

Read more: Aborting the Pipeline on Workflow failure.

pipelines:
  example:
    workflows:
      A: {}
      B:
        abort_on_fail: true

This property defines whether a Workflow should run if a previous Workflow failed.

Be aware of transitive dependency: if a Workflow that is set to always run has a parent Workflow that fails, it will still run. However, Workflows that depend on it will not. For example, let's say we have Workflow C that depends on Workflow B. Workflow B depends on Workflow A. Of the three Workflows, only B is set to always run:

Supported values:

Read more: Always executing a Workflow in a Pipeline

pipelines:
  example:
    workflows:
      A: {}
      B:
        depends_on: [ A ]
        should_always_run: workflow
      C:
        depends_on: [ B ]
      D:
        depends_on: [ C ]
        should_always_run: workflow

A Go template expression that defines the conditions for running the Workflow.

The property needs an expression field that contains a Go template, with three helper functions:

The Bitrise CLI evaluates the expression during runtime. If a Workflow is skipped because of a run_if expression, it will be counted as a successful Workflow so its dependent Workflows will run.

Read more: Examples of run_if expressions.

pipelines:
  example:
    workflows:
      A: {}
      B:
        run_if:
          expression: {{ enveq "EXAMPLE_KEY" "example value" }}
        depends_on: [A]

The parallel property allows you to run copies of the same Workflow in parallel, in a single instruction. This is particularly useful for test sharding.

The property determines the number of copies running in parallel. Each copy receives two new environment variables:

Supported values: An integer.

Read more: Running variations of the same Workflow.

The title of the Workflow.

It appears on the UI of the Workflow Editor.

workflows:
  primary:
    title: Primary Workflow

A short summary of the Workflow.

workflows:
  primary:
    summary: This Workflow runs unit tests.

A detailed description of the Workflow.

workflows:
  primary:
    description: This Workflow runs unit tests with test sharding, and exports the test results to the test reports page. 

Target-based triggers defined for the Workflow: if a code event matches the condition defined in a trigger, Bitrise will trigger a build with the Workflow.

Each trigger defines a code event and at least one condition. If you define multiple conditions in a single trigger, all of them must match to trigger a build.

For the detailed syntax of the triggers property and its available options, check out:

Read more: YAML syntax for build triggers.

workflows:
  primary:
    triggers:
      push:
      - branch: main
      pull_request:
      - source_branch: "*"

The name that will appear on the status report sent to connected services (like GitHub, GitLab, Bitbucket, and so on) after the build is finished.

It can have both static and dynamic values, as well as combine the two types.

Supported characters and variables:

workflows:
  test:
    status_report_name: ci/bitrise/510526/push

The Workflows that will run before this Workflow starts.

Use this property and after_run to create chains of Workflows.

Read more: Chaining Workflows together.

workflows:
  test:
    steps:
    # test Steps

  deploy:
    before_run:
    - test
    steps:
    # deploy Steps

The Workflows that will run after this Workflow is successfully finished.

Use this property and before_run to create chains of Workflows.

Read more: Chaining Workflows together.

workflows:
  deploy:
    steps:
    # deploy Steps

  ci:
    after_run:
    - deploy
    steps:
    # CI Steps

Environment Variables defined for the Workflow.

Each Environment Variable is a key-value pair. Environment Variables can use other Environment Variables as values: Using Env Vars in the value of an Env Var.

These variables are only available for the selected Workflow. Other Workflows defined in the same configuration YAML file can't access them. Project-level Environment variables have a higher priority: Availability order of Environment Variables.

Read more: Environment Variables.

workflows:
  primary:
    envs:
    - TEST: test
    - ENV_LABEL: dev
      opts:
        is_expand: false

The list of Steps in the Workflow.

The basic syntax of a Step reference is: <step_lib_source>::<step-id>@<version>:. The Step ID is always required; the source and the version are optional.

Read more:

workflows:
    steps:
    - script: {}

workflows:
    steps:
    - https://github.com/bitrise-io/bitrise-steplib.git::script@1: {}

The priority setting determines the position of the Workflow build in the build queue: the higher the priority, the sooner the Workflow build will run.

Supported values: An integer between -100 and 100.

Read more: Build priority.

workflows:
  primary:
    priority: 10

Declarative configuration for tool versions used in the build.

You can define tool versions for specific Workflows. Instead of defining the tools property at the top level of the configuration, you nest it under one or more Workflows.

The version syntax supports:

Read more: Configuring tool versions.

workflows:
  primary:
    tools:
      nodejs: 22:installed

Stores project metadata key-value pairs. Most importantly, it defines the stack and the machine type for the Workflow.

Read more: Setting the stack in the Configuration YAML.

workflows:
  deploy:  
    meta:      
      bitrise.io:       
        stack: linux-docker-android-22.04
        machine_type_id: g2.linux.2medium

The title of the Step.

This appears on the Workflow Editor, replacing the Step ID.

workflows:
    steps:
    - script@1:
        title: Test sharding script

A short summary of the Step.

workflows:
    steps:
    - script@1:
        summary: Custom script for sharding.

A detailed description of the Step.

workflows:
    steps:
    - script@1:
        summary: A custom script for setting up test sharding for Flutter unit tests. 

If this property is true, the Step will always run, even if a previous Step in the Workflow failed.

By default, if a previous Step fails in the Workflow, subsequent Steps will not run. A Step will only run if this property is set to true.

Supported values: boolean

Read more: Configuring a Step to always run.

workflows:
  primary:
    steps:
    - script:
        is_always_run: true

If this property is true, the build won't fail even if this Step fails.

By default if a Step fails, subsequent Steps are not executed. If the first failing step has this property set to true, it won't make the build fail. Subsequent Steps will still run and the build can finish successfully.

Supported values: boolean

workflows:
  primary:
    steps:
    - script:
        is_skippable: true

This property sets conditions for running a Step. It requires a valid Go template expression.

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

Read more:

run_if: |-
        {{enveq "CUSTOM_ENV_VAR_KEY" "test value to test against"}}

This property defines a time limit for a Step: if the Step runs longer than the defined time, the Step fails. Define the limit in seconds.

This is useful if, for example, your builds hang for not immediately obvious reasons - you can set timeouts for the Step or Steps which are suspected to have caused the problem.

Read more: Setting a time limit for Steps.

- xcode-test:
     timeout: 120

This property defines a time limit for steps: if a Steps runs longer than the defined time without producing an output, the Step fails. Define the limit in seconds.

Read more: Detecting and aborting hanging Steps without output.

  output_slows_down:
    steps:
    - script:
        no_output_timeout: 12

Inputs defined for the Step: these are values that can be set when the Step is added to a Workflow.

Step input syntax consists of a KEY: value pair.

Read more: Step inputs reference.

inputs:
- my_key_for_the_env: "default value"

Outputs defined for the Step: these are values that the Step can set during its execution, which can be used by other Steps in the Workflow.

You can check out the default outputs of a Step in the Workflow Editor on bitrise.io or in the step.yml file of the Step. Step outputs can be defined in the step.yml file of the project by setting the outputs attribute. Step out syntax consists of two main parts: a KEY: value pair and an opts field. The key and the value are required, the opts field is optional.

Read more: Step outputs reference.

workflows:
  primary:
  steps:
  - gradle-runner:
      outputs:
      - BITRISE_APK_PATH: ALIAS_APK_PATH

The property determines whether a defined trigger is active. The default value is true. If you want to disable the trigger, set it to false.

Supported values: boolean

workflows:
  primary:
    triggers:
      enabled: false

Code push triggers define the conditions for triggering a Bitrise build when code is pushed to the project's repository.

For example, a commit to the specified branch of the project's repository triggers a build.

workflows:
  primary:
    triggers:
      push:
      - branch: main

workflows:
  primary:
    triggers:
      push:
      - branch: main

primary
  triggers:
    push:
    - commit_message:
        regex: '.*\[workflow: deploy\].*'

primary
  triggers:
    push:
    - changed_files: 
        pattern: "myfile.txt"

Pull request triggers: they define the conditions for triggering a Bitrise build when a pull request is opened in the project's repository.

primary
  triggers:
    pull_request:
    - source_branch: *

primary
  triggers:
    pull_request:
    - source_branch: main

primary
  triggers:
    pull_request:
    - target_branch: main

primary
  triggers:
    pull_request:
    - label: bugfix

primary
  triggers:
    pull_request:
    - draft_enabled: false

primary
  triggers:
    pull_request:
    - comment: approved

primary
  triggers:
    pull_request:
    - commit_message: "fix for issue"

primary
  triggers:
    pull_request:
    - changed_files: ./path/to/file

Git tag triggers define the conditions for triggering a Bitrise build when a Git tag is pushed to the project's repository.

primary
  triggers:
    tag:
    - name: *

primary
  triggers:
    tag:
    - name: 1.0