Managing an app's bitrise.yml file

Abstract

The heart of your build is the bitrise.yml file. You can configure the Steps you use, the project type, the trigger map, and specify the app- and Workflow-level Env Vars.

The bitrise.yml file is the heart of your Bitrise setup: it stores your entire build configuration for an app. It specifies your stack, the trigger map, and what Workflows and Steps are included. When you edit your Workflows on the graphical UI of our Workflow Editor, you actually modify the bitrise.yml file.

YAML files size limitation

Please note that the total, combined size of the bitrise.yml and the bitrise.secrets.yml file cannot exceed 400KB.

There are two ways to manage the bitrise.yml file of your app:

Keep the file in your Git repository: with this solution, you have full control over maintaining and versioning the bitrise.yml file.
Keep it on bitrise.io: Bitrise will store your configuration, and you can access it any time on the website. With this solution, the configuration file is fully independent from your repository.

You can switch between the two solutions at any time.

bitrise.yml reference

You can find detailed reference information about the bitrise.yml file in our relevant guide: Basics of bitrise.yml.

Storing the bitrise.yml file in your repository

Privately hosted repositories

Unfortunately, this feature is not yet supported for users who can't use the service credential user integration; for example, if the repository is is only accessible under a private IP subnet. There's a workaround, however: Storing the bitrise.yml in a privately hosted repository.

This workaround works, for example, for GitHub Enterprise and Bitbucket Server users.

When you store the bitrise.yml configuration file in your repository, the build process on Bitrise will use that file to run your builds. This means that:

You have full control over versioning your configuration file.
Every time you make a change to your Workflows or your trigger map, you must commit the changes to the file in the repository.

You don’t need to create your own bitrise.yml file in advance: you can use the file stored on bitrise.io. Let's see how to store the bitrise.yml file in a repository that does not contain one yet.

Multiple apps with the same repository

You can only store a single bitrise.yml file in a given repository. Bitrise will look for the file in the root directory, and as such, currently there’s no way to include two in separate folders.

If you have two or more Bitrise apps connected to the same repository, you can store all their Workflows in the same bitrise.yml file. Of course each Workflow must have a different name: you can’t have two primary Workflows in the same file, for example.

Open the app on Bitrise and go to the Team tab.
Check the Service credential user section. The service credential user must be a Bitrise user who has at least read access to the repository.

Service credential integration

Be aware that if your app uses a repository where the Service credential user integration is not supported - for example, the repository is only accessible under a private IP subnet -, the feature won’t work as the website can’t grab the bitrise.yml due to IP addressing limitations.
Go to the Workflow tab.
In the Workflow Editor, go to the bitrise.yml tab.
Click Store in app repository.
When prompted to add the bitrise.yml to your app's repository, you have two options:
- Copy the content of the current bitrise.yml file to the clipboard. You can then create your own file and copy the contents into it.
- Download the current bitrise.yml file.
In your repository, commit the bitrise.yml file to the root of the default branch.

Branches of the repository

The default branch of your app must always have a bitrise.yml file on it. You can store different bitrise.yml files on the other branches: Storing a bitrise.yml file on multiple branches in the repository.

You can check your Bitrise app's default branch on bitrise.io by going to the Settings tab and finding the DEFAULT BRANCH option.
On Bitrise, click Update setting.
When prompted to make sure your bitrise.yml file is valid, click Continue.

Make sure the file is valid

The bitrise.yml file in your repository always must be valid! If it contains incorrect syntax, it can break your builds.

If all goes well, you should receive confirmation of successfully changing your bitrise.yml storage settings.

Allowlist the Bitrise website IP addresses

If you use some form of self-hosted solution for storing your code, you might need to allowlist the static IP addresses of the Bitrise website and its background workers. This allows you to use such features as storing the bitrise.yml file in your own repository, or receiving build status updates from Bitrise: IP addresses for the Bitrise website.

Updating a bitrise.yml stored in the repository

When you store the bitrise.yml file in your repository, you can still use the online Workflow Editor to make changes to your build configuration. You just need to commit your changes after saving them in the Workflow Editor:

Open your app on Bitrise.
Click the Workflows button on the main page.
On the Workflows & Pipelines pages, you can:
- Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
- Click the button next to the name of any Workflow to open it in the Workflow Editor.
Make changes to the Workflows you want to update.
Click Save in the top right corner.
You're prompted to update the bitrise.yml file in your repository. You have two options:
- Copy the content of the current bitrise.yml file to the clipboard. You can then create your own file and copy the contents into it.
- Download the current bitrise.yml file.
In your repository, commit the bitrise.yml file.

Branches of the repository

The default branch of your app must always have a bitrise.yml file on it. You can store different bitrise.yml files on the other branches: Storing a bitrise.yml file on multiple branches in the repository.
On Bitrise, click I'm done to fetch the bitrise.yml from your repository.

Commit your changes before clicking I'm done

If you haven't committed your changes to the repository, this will overwrite them!

Storing a bitrise.yml file on multiple branches in the repository

When you first add the bitrise.yml to your repository, it must be committed to the default branch. You can check out the app’s default branch on bitrise.io under the Settings tab.

If you choose to store the bitrise.yml file in the repository, the default branch must have a bitrise.yml!

However, once you did the initial configuration to set up using the bitrise.yml from your repository, you can store bitrise.yml files on other branches and use any of them to run builds. If you want to build a branch of your repository on Bitrise, you need to have a bitrise.yml file on that branch. And don’t forget that you always need to keep a bitrise.yml file on the default branch.

Example 1. Bitrise setup with bitrise.yml files on multiple branches

Let’s say you have an app called FantasticApp. In FantasticApp’s Git repository, the default branch is called main. There is also a deploy branch.

Any code push or pull request to main triggers a Workflow called main-workflow. Any code push or pull request to deploy triggers a Workflow called deploy-workflow.

In the repository, there is a bitrise.yml file on both the main and the deploy branch, containing both Workflows. When making changes to the Workflows, the FantasticApp team commits the modified bitrise.yml file to both branches to ensure that their Workflows are up to date on both.

Moving the bitrise.yml file back to bitrise.io

The default setting is to store the bitrise.yml file on bitrise.io: when you add a new app, we automatically create a bitrise.yml file for you and it’s stored on our website. If this works for you, then you don’t need to change anything!

If, however, you changed your storage settings to keep the configuration file in your repository, you can easily change it back any time to store the file on bitrise.io.

Open the app on Bitrise.
Go to the Workflows tab.
In the Workflow Editor, go to the bitrise.yml tab.
Click Store on bitrise.io.
Choose which bitrise.yml file should be used on bitrise.io from now.
- You can copy the content of the bitrise.yml file stored in the app’s repository.
- You can copy the last version of the bitrise.yml file that you used on bitrise.io.
Click Update setting.

If all goes well, you should receive confirmation of successfully changing your bitrise.yml storage settings.

In this section: