Managing an app's bitrise.yml configuration

Last updated at 2020-08-24

The bitrise.yml file is the heart of your Bitrise setup: it stores your build configuration, right down to Step input values, the trigger map, and stack information. When you edit your Workflows on the graphical UI of our Workflow Editor, you actually modify the bitrise.yml file.

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

You can switch between the two solutions at any time.

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.

Storing the bitrise.yml file in your repository

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:

Service credential user

In order to be able to use the feature, you must set the Service credential user correctly: it must be a user who has at least read access to the repository at your app’s hosting service.

To check the Service credential user, go to the Team tab of your app, and find the Service credential User option. If you need to change it, keep in mind that for security reasons, you can only select your own account as service credential user. If you don’t have read access to your app’s repository at your hosting service, you can’t set the appropriate Service credential user.

Repository access

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.

The feature is definitely supported for the following hosting services:

  • GitHub
  • BitBucket
  • GitLab
  • Self-hosted GitLab (as long as the repository is not on a private network).

To store the file in your repository, you must commit it to the root of your Bitrise app’s default branch. You can check the app’s default branch on open the app, and go to the Settings tab. Scroll down to the DEFAULT BRANCH option to check which branch should contain the bitrise.yml file.

You don’t need to create your own bitrise.yml file in advance to use this solution though: during the process of updating your settings, you will have the chance to download the current file from the website, or copy its full content. Once you commit that file to the appropriate branch, you can change the setting. Let’s see how to do that:

The bitrise.yml file must be valid!

Always make sure that the bitrise.yml file in the repository is valid: a bitrise.yml with incorrect syntax will break your builds!

  1. Open the app on Bitrise.
  2. Go to the Workflows tab.
  3. In the Workflow Editor, go to the bitrise.yml tab.
  4. Click Store in app repository.
  5. If you don’t have a bitrise.yml file the repository, you will be prompted to add one.

    You can download the current bitrise.yml file from the website, or copy its entire content to the clipboard. Either way, you have to commit the file to the root directory of the repository to proceed. Remember: you must commit the file to the branch that is set as the default branch on! You can check the default branch under the Settings tab on our website.

  6. Click Update setting.
  7. When prompted to make sure your bitrise.yml file is valid, click Continue.

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

Storing the bitrise.yml file on

The default setting is to store the bitrise.yml file on 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

  1. Open the app on Bitrise.
  2. Go to the Workflows tab.
  3. In the Workflow Editor, go to the bitrise.yml tab.
  4. Click Store on
  5. Choose which bitrise.yml file should be used on 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
  6. Click Update setting.

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

Accessing a build’s bitrise.yml

Every bitrise.yml file is stored for your builds on They come in handy when you’d like to check the configuration with which a specific build has run. To do that, you can either use the online Workflow Editor or your build’s online bitrise.yml file. If you choose the latter, you can compare changes, restore the current build to the original version, edit the config, and download the file to your computer.

Using filters on your Builds Board

If an app has multiple builds on and you want to pick a specific build out of those, then these filters will help you a lot. Click on your app in your Dashboard and use the following fields:

  • You can search for a build number or commit message in the Try build number or commit message grey field.
  • You can pick which of these triggers was used for your build: Pushes, Pull Requests, Tags or all of these.
  • You can pick which branch the build was started on.
  • You can select either the primary or the deploy workflow of the build.

  1. Select an application on your Dashboard and select one of its builds.
  2. Click the Show bitrise.yml button at the top OR at the bottom of your inline log.

    You should see your build’s bitrise.yml content displayed in ace editor but it’s not editable here. See where you can edit the bitrise.yml online.

Checking changes in bitrise.yml online

Once you’ve clicked Show bitrise.yml, you will see the BUILD’S BITRISE YML pop-up window displaying your builds’ configuration details. If the build’s bitrise.yml content differs from the current build’s bitrise.yml, you will see two editors displayed side-by-side in the BITRISE.YML CHANGES pop-up window. The differences between the builds are highlighted in the following colors:

Restoring and undoing changes in bitrise.yml online

If you don’t like the changes made to your current bitrise.yml, you can easily restore it to the build’s original bitrise.yml.

  1. Click the Show bitrise.yml button at the top OR at the bottom of your inline log on
  2. In the BITRISE.YML CHANGES pop-up window, click the orange Restore button.
  3. Hit OK in the Are you sure? pop-up window to confirm and override the current bitrise.yml.

Editing and downloading bitrise.yml online

You can edit your build config in yml format in the bitrise.yml editor if you go to your app’s Workflow Editor and click the bitrise.yml tab.

You can save or discard any changes you have made with the config. If you click Download currently saved config, you can download this YML version to your own computer and run it with bitrise CLI on your computer.

You might want to copy this whole YML configuration or just part of it to another app, so that you can use the copied version as a base and extend it with a few extra steps. All you have to do is copy this bitrise.yml content and paste it into the new app’s bitrise.yml editor and develop it further.

Deleting a build’s bitrise.yml

If you wish, you can simply delete a build’s bitrise.yml file. But please note that this action cannot be undone: nobody will be able to view that particular build’s bitrise.yml file once you delete it.

  1. Select an application on your Dashboard and select one of its builds.
  2. Click the Delete bitrise.yml button.

  3. In the confirmation window, click Yes.