- Home
- Builds
- Configuration YAML
- Storing an app's configuration YAML
Storing an app's configuration YAML
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.
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 store the bitrise.yml
file of your project:
-
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 configuration YAML.
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:
-
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.
The feature requires service credential integration or the GitHub App integration. Hosting the bitrise.yml
file in a privately hosted repository where neither is available needs a workaround.
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 the code for multiple Bitrise apps in the same repository, we recommend using different
Workflows for the different apps.
-
Open the app on Bitrise and go to the App settings page.
-
Select Collaboration.
-
Check the Service credential user section. The service credential user must be a Bitrise user who has at least
read
access to the repository. -
Open the Workflow Editor.
-
In the Workflow Editor, select Configuration YAML from the navigation menu on the left.
-
Above the YAML file, you can see where the file is currently stored. Click Change.
-
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.The default branch of your app must always have a
bitrise.yml
file on it. You can store differentbitrise.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 Validate and save.
Validation
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 address ranges for Bitrise backend workers.
Privately hosted repositories
Unfortunately, this feature is not yet supported for users who can't use the service credential user integration or the GitHub App 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 Bitbucket Server users.
For GitHub Enterprise, we offer an integration that allows you to store your bitrise.yml
file in a GitHub Enterprise repository: Integrating self-hosted GitHub Enterprise Server with Bitrise.
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.
Read-only mode
You can't directly edit the bitrise.yml
file itself in the Workflow Editor. You need to use the GUI to make changes, or edit the file in your repository instead.
-
Log in to Bitrise and select Bitrise CI on the left, then select your project.
-
Click the Workflows button on the main page.
-
Make changes to the Workflows you want to update.
-
Click Save changes 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. -
On Bitrise, click I'm done to fetch the
bitrise.yml
from your repository.Commit your changes first!
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. If you store the
bitrise.yml
file in the repository, the default branch must always 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.
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.
-
Log in to Bitrise and select Bitrise CI on the left, then select your project.
-
Click the Workflows button on the main page.
-
In the Workflow Editor, select Configuration YAML from the navigation menu on the left.
-
Click Change next to the source of the file.
-
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 Validate and save.
If all goes well, you should receive confirmation of successfully changing your bitrise.yml
storage settings.
The bitrise.yml
file stores your entire build configuration for an app. It specifies your stack and the build triggers, and
defines the Workflows of the app. When you make changes on the graphical UI of our Workflow Editor, you actually modify the bitrise.yml
file.