Corporate logotype
  • Go to Support
  • Book a demo
Corporate logotype
  • Getting started
    • Migrating to Bitrise
      • Migrating from Jenkins to Bitrise
    • Signing up for Bitrise
      • Creating your first Workspace
      • Adding your first app
      • Getting started with iOS apps
        • Getting started with Android apps
          • Getting started with React Native apps
            • Getting started with Flutter apps
              • Getting started with Ionic/Cordova apps
                • Getting started with Expo apps
                  • Getting started with MacOS apps
                  • Infrastructure
                    • Build machines
                      • Configuring network access for Bitrise build machines
                      • Storage space on build machines
                      • Freeing up storage space on build machines
                      • Customizing build machines
                    • Build stacks
                      • Stack update policy
                      • Stack deprecation and removal policy
                      • Preinstalled tools on Bitrise stacks
                      • The Android/Linux/Docker environment
                      • Managing Java versions
                    • Code security
                      • Customizable enterprise build platforms
                        • Using your own Docker image
                          • Running your build locally in Docker
                          • Accounts
                            • Connecting to services
                              • The service credential user
                              • Connecting your GitHub/GitLab/Bitbucket account to Bitrise
                              • Connecting self-hosted GitLab instances
                              • Apple services connection
                              • Connecting to an Apple service with API key
                              • Connecting to an Apple service with Apple ID
                              • Connecting to an Apple Service with Step inputs
                              • Steps requiring Apple authentication
                            • SAML SSO in Bitrise
                              • Setting up Google SSO for Bitrise
                              • Setting up AD FS SSO for Bitrise
                              • Setting up Azure AD SSO for Bitrise
                              • Setting up Auth0 SSO for Bitrise
                              • Setting up Idaptive SAML SSO for Bitrise
                              • Setting up Okta SSO for Bitrise
                              • Setting up Ping Identity SSO for Bitrise
                              • Setting up OneLogin SSO for Bitrise
                            • Editing your profile settings
                              • Resetting your password
                              • Two-factor authentication
                                • Personal access tokens
                                  • Deleting your Bitrise account
                                • Workspaces
                                  • Creating Workspaces
                                  • Workspace billing and invoicing
                                    • Adding other users to Workspaces
                                      • Changing the owners of a Workspace
                                      • Workspace FAQ
                                    • Apps
                                      • Webhooks
                                        • Adding incoming webhooks
                                        • Adding a GitHub webhook
                                        • Adding a Gitlab webhook
                                        • Adding a Bitbucket webhook
                                        • Adding a Gogs webhook
                                        • Adding a Slack webhook
                                        • Adding a Visual Studio webhook
                                        • Adding an Assembla webhook
                                        • Adding a Deveo webhook
                                        • Adding outgoing webhooks
                                      • Configuring the repository URL and default branch
                                        • Configuring SSH keys
                                        • Adding team members to an app
                                          • User roles on app teams
                                            • Changing the owner of an app
                                              • Enabling the Bitrise Support user for your app
                                              • Apps with submodules or private repo dependencies
                                                • Public apps
                                                • Creating white label app versions
                                                • Steps and Workflows
                                                  • Steps
                                                    • Adding Steps to a Workflow
                                                    • Step versioning
                                                    • Step inputs
                                                    • Skipping Steps
                                                    • Enabling or disabling a Step conditionally
                                                    • Setting a time limit for Steps
                                                  • Developing your own Bitrise Step
                                                    • Developing a new Step
                                                    • Sharing Steps with all Bitrise users
                                                    • Verified Steps
                                                    • Creating your own Bitrise project scanner
                                                  • Workflows
                                                    • Default Workflows
                                                    • Creating a Workflow
                                                    • Managing Workflows
                                                    • Copying Workflows from one app to another
                                                  • Workflow recipes for Android apps
                                                    • (Android) Deploy to Visual Studio App Center
                                                    • (Android) Deploy to Firebase App Distribution
                                                    • (Android) Deploy to Google Play (Internal, Alpha, Beta, Production)
                                                    • (Android) Deploy to Bitrise.io
                                                    • (Android) Example CI Workflow
                                                    • (Android) Example nightly Workflow
                                                    • (Android) Example pull request Workflow
                                                    • (Android) Run instrumentation tests on virtual devices
                                                    • (Android) Example release Workflow
                                                    • (Android) Run Lint
                                                    • Turn on Gradle build profiling
                                                    • (Android) Run unit tests
                                                    • (Android) Run tests using the emulator
                                                  • Workflow recipes for iOS apps
                                                    • (iOS) Deploy to Visual Studio App Center
                                                    • (iOS) Cache CocoaPods dependencies
                                                    • (iOS) Deploy to App Store Connect / TestFlight
                                                    • (iOS) Example CI Workflow
                                                    • (iOS) Deploy to bitrise.io
                                                    • (iOS) Example pull request Workflow
                                                    • (iOS) Deploy to Firebase App Distribution
                                                    • (iOS) Example nightly Workflow
                                                    • (iOS) Run tests on a physical device
                                                    • (iOS) Run tests on a simulator
                                                    • (iOS) Install CocoaPods dependencies
                                                    • (iOS) Install Carthage dependencies
                                                    • (iOS) Example release Workflow
                                                  • Workflow recipes for cross-platform apps
                                                    • (React Native) Cache dependencies (node_modules)
                                                    • (React Native) Expo: Build using Turtle CLI
                                                    • (React Native) Run tests
                                                    • (React Native) Install dependencies
                                                    • (Flutter) Run tests
                                                    • (Flutter) Install Flutter SDK
                                                    • (Flutter) Run Dart Analyzer
                                                  • Generic Workflow recipes
                                                    • (iOS/Android) Send build status to Slack
                                                    • Cloning a Git repository
                                                    • Shallow clone a Git repository
                                                    • Example Gitflow release branch Workflow
                                                    • (iOS/Android) Send QR code to Slack
                                                    • Start builds from a parent Workflow
                                                    • Optimizing cache efficiency for pull request builds
                                                    • GitHub pull request: send the build QR code
                                                • Builds
                                                  • Configuring build settings
                                                    • Setting the stack for your builds
                                                    • Managing an app's bitrise.yml file
                                                    • Editing the app's bitrise.yml file
                                                    • Accessing a build's bitrise.yml file
                                                    • Selective builds
                                                    • Rolling builds
                                                    • Configuring email notifications
                                                    • Configuring Slack integration
                                                    • Setting your Git credentials on build machines
                                                    • Reporting the build status to your Git hosting provider
                                                  • Starting builds
                                                    • Starting builds manually
                                                    • Triggering builds automatically
                                                    • Scheduling builds
                                                    • Approving pull request builds
                                                    • Using the Trigger Map to trigger builds
                                                    • Starting parallel builds with a single trigger
                                                    • Skipping a given commit or pull request
                                                  • Caching
                                                    • Using caching in your builds
                                                    • Caching Cocoapods
                                                    • Caching Gradle
                                                    • Caching Maven
                                                    • Caching Ruby Gems
                                                    • Caching Homebrew installers
                                                  • Managing build files
                                                    • Uploading files for your builds
                                                    • Using files in your builds
                                                    • Using encrypted files in your builds
                                                    • Build artifacts online
                                                  • Environment Variables
                                                    • Secrets
                                                      • Build statuses
                                                      • Installing tools during a build
                                                        • Connecting to a VPN during a build
                                                          • Finding a specific build
                                                          • Build numbering and app versioning
                                                            • Build data and troubleshooting
                                                              • Build logs
                                                              • Remote access
                                                              • Debugging your build on your own machine
                                                              • Bitrise Checks on GitHub
                                                              • Monitoring your builds with Meercode
                                                              • Checking build details
                                                          • Code signing
                                                            • Android code signing
                                                              • Android code signing using the Android Sign Step
                                                              • Android code signing with Android Studio
                                                              • Android code signing in Gradle
                                                              • Downloading a keystore file
                                                            • iOS code signing
                                                              • Collecting and exporting code signing files with codesigndoc
                                                              • iOS code signing with automatic provisioning
                                                              • Managing iOS code signing files - manual provisioning
                                                              • Creating a signed IPA for Xcode projects
                                                              • Signing an IPA with multiple code signing identities
                                                              • iOS code signing for Ionic and Cordova projects
                                                              • Protecting your code signing files
                                                              • Generating iOS code signing files
                                                              • Exporting iOS code signing files manually
                                                              • Troubleshooting iOS code signing
                                                          • Testing
                                                            • Test Reports
                                                              • Exporting to Test Reports from any Step
                                                                • Running Xcode tests
                                                                  • Installing an ipa file from the public install page
                                                                    • Registering a test device
                                                                      • Device testing for iOS
                                                                        • Android unit tests
                                                                          • Device testing for Android
                                                                            • Running tests in the Visual Studio App Center
                                                                            • Running Detox tests on Bitrise
                                                                            • Deploying
                                                                              • Android deployment
                                                                                • Deploying Android apps to Bitrise and Google Play
                                                                                • Deploying apps to Huawei AppGallery
                                                                                • Generate and deploy multiple flavor APKs in a single workflow
                                                                                • Generating and deploying Android app bundles
                                                                                • Exporting a universal APK from an AAB
                                                                              • iOS deployment
                                                                                • Deploying an iOS app to Bitrise.io
                                                                                • Deploying an iOS app for external testing
                                                                                • Deploying an iOS app to iTunes Connect
                                                                                • Deploying an iOS app for simulators
                                                                              • Bitrise OTA app deployment
                                                                                • Deploying with Ship
                                                                                  • Getting started with Ship
                                                                                  • Configuring an app for publishing with Ship
                                                                                  • Installing an app on a test device with Ship
                                                                                  • Publishing an app to a store with Ship
                                                                                  • Using Ship for apps built with cross-platform frameworks
                                                                                  • App details in Ship
                                                                                  • Ship notifications
                                                                                • Deploying apps to Applivery
                                                                                  • Deploying apps to DeployGate from Bitrise
                                                                                  • Deploying your app to Appaloosa
                                                                                  • Deploying to TestFairy with Bitrise
                                                                                • Build Insights
                                                                                  • Getting started with Insights
                                                                                    • Available metrics in Insights
                                                                                      • Test stats in Build Insights
                                                                                      • Bitrise CLI
                                                                                        • Installing and updating the Bitrise CLI
                                                                                          • Adding a new app from a CLI
                                                                                          • Initializing a Bitrise project locally
                                                                                          • Installing and upgrading the offline Workflow Editor
                                                                                            • Running your first local build with the CLI
                                                                                            • Managing Secrets locally
                                                                                          • API
                                                                                            • Authenticating with the Bitrise API
                                                                                            • Pagination of API calls
                                                                                            • Adding and managing apps
                                                                                              • Triggering and aborting builds
                                                                                                • Incoming and outgoing webhooks
                                                                                                  • Managing iOS code signing files
                                                                                                    • Managing files in Generic File Storage
                                                                                                      • Managing build artifacts
                                                                                                        • API reference
                                                                                                      • References
                                                                                                        • Basics of bitrise.yml
                                                                                                        • Customizing the bitrise.yml config
                                                                                                        • Workflow reference
                                                                                                        • Steps reference
                                                                                                          • Step reference/ID format
                                                                                                          • Step data in the bitrise.yml file
                                                                                                          • Step properties
                                                                                                          • Step inputs reference
                                                                                                          • Step outputs reference
                                                                                                        • Available environment variables
                                                                                                        • Bitrise tools
                                                                                                      • Go to Support
                                                                                                      • Book a demo
                                                                                                      print
                                                                                                      • Prev
                                                                                                      • Next
                                                                                                      • Welcome to Bitrise documentation!
                                                                                                      • Builds
                                                                                                      • Configuring build settings
                                                                                                      • Managing an app's bitrise.yml file

                                                                                                      Managing an app's bitrise.yml file

                                                                                                      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 200KB.

                                                                                                      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.

                                                                                                      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.

                                                                                                      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.

                                                                                                      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.

                                                                                                      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.

                                                                                                      1. Open the app on Bitrise and go to the Team tab.

                                                                                                      2. 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.

                                                                                                      3. Go to the Workflow tab.

                                                                                                      4. In the Workflow Editor, go to the bitrise.yml tab.

                                                                                                      5. Click Store in app repository.

                                                                                                      6. 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.

                                                                                                      7. 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.

                                                                                                      8. On Bitrise, click Update setting.

                                                                                                      9. 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.

                                                                                                      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:

                                                                                                      1. Open your app on Bitrise.

                                                                                                      2. Go to the Workflow tab.

                                                                                                      3. Make changes to the Workflows you want to update.

                                                                                                      4. Click Save in the top right corner.

                                                                                                      5. 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.

                                                                                                      6. 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.

                                                                                                      7. 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.

                                                                                                      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 bitrise.io.

                                                                                                      5. 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.

                                                                                                      6. Click Update setting.

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

                                                                                                      In this section:
                                                                                                      See also:
                                                                                                      • Secrets
                                                                                                      • Basics of bitrise.yml
                                                                                                      • Customizing the bitrise.yml config
                                                                                                      • Workflow reference
                                                                                                      • Managing an app's bitrise.yml file
                                                                                                      • Storing the bitrise.yml file in your repository
                                                                                                      • Updating a bitrise.yml stored in the repository
                                                                                                      • Storing a bitrise.yml file on multiple branches in the repository
                                                                                                      • Moving the bitrise.yml file back to bitrise.io

                                                                                                      Search results

                                                                                                        No results found

                                                                                                        Was this helpful?

                                                                                                        Would you like to provide feedback? Just click here to suggest edits.

                                                                                                        • Prev
                                                                                                        • Next
                                                                                                        © 2022
                                                                                                        Publication date: