Basics of configuration YAML

Abstract

The bitrise.yml file is the heart of your Bitrise configuration. The Bitrise CLI needs this file to be able to run Bitrise builds, either locally or on our website.

Your Bitrise configuration is defined in one or more YAML files. The Bitrise CLI needs a configuration YAML file to be able to run Bitrise builds, either locally or on our website.

The default configuration YAML file is called bitrise.yml. A bare minimal bitrise.yml is as simple as:

format_version: 11

The above configuration is valid but does not include anything to execute with run.

A minimal configuration which you can bitrise run:

format_version: 5
workflows:
  test:

The above configuration can be executed with bitrise run test. The Bitrise CLI won’t give you any errors, but there’s still nothing declared to do.

Let’s continue with an example that executes a single Script Step when you run it with bitrise run test.

format_version: 11
default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git
project_type: android
app:
  envs:
  - MY_NAME: My Name
workflows:
  test:
    steps:
    - script@1.1.5:
        inputs:
        - content: echo "Hello ${MY_NAME}!"

A quick walk through of this sample configuration:

format_version : declares the minimum Bitrise CLI format version. Get your Bitrise CLI’s supported highest format version with bitrise version --full.

Format version number

The format version number determines what Bitrise CLI versions will be able to run the configuration. For example, if you set the format_version to 11 that means that Bitrise CLI versions which don’t support the format version 11 or higher won’t be able to run the configuration. This is important if you use features which are not available in older Bitrise CLI versions.
default_step_lib_source : specifies the source to use when no other source is defined for a Step.
project_type : defines your source project’s type (for example, android, ios, flutter).
app - envs : specifies the Environment Variables (Env Var) which will be available for every build, workflow and step.
workflows : is the collection of separate build configurations which you can run with bitrise run WORKFLOWID.

In our example the only workflow is test, which you can perform with bitrise run test. If you’d have a second workflow called main, you could run both bitrise run test and bitrise run main.
steps : lists the Steps which should be executed when the Workflow is run.

In our example the test workflow includes only a single script Step. If multiple Steps are declared, they are performed one by one.
script@1.1.5 : a Step (reference) to perform. This reference does not have a StepLib Source declaration, which means that the default_step_lib_source will be used as the StepLib Source.
inputs : specifies Step inputs.

Multiple inputs

A Step can have many inputs. Specify only those input in the bitrise.yml which you want to set or overwrite.
content : the input you want to set.

In our example, we specified the content of the Script Step.
echo "Hello ${MY_NAME}!" : this is the value we specified for the content input.

bitrise.yml size limitation

If you edit your Workflow on bitrise.io (either in the Workflow Editor or on the bitrise.yml tab) and your bitrise.yml exceeds its size limitation, the UI will display the following warning upon trying to save your changes:

Error saving! Error saving app config: Validation failed: App config validation 784: unexpected token at 'Argument list too long - bin/bitrise

This is because the total, combined size of the bitrise.yml and the bitrise.secrets.yml file cannot exceed 400KB.

In this section:

Basics of configuration YAML

Format version number

Multiple inputs

bitrise.yml size limitation

Search results