Allow bitrise.yml to be pulled from project source code


From @viktorbenei on Thu Jun 16 2016 07:27:46 GMT-0400 (EDT)

Related UserVoice link:

Summary and proposal

We know that version control for the configuration is quite important, but having the configuration stored separately has its own advantages, especially when you want to quickly iterate, or if you want to allow a UI (e.g. Workflow Editor on to edit it, without granting direct access to the repository (it should not have the possibility to change the code repository, as you can never know what might go wrong).

An alternative solution we’re thinking about is to give you direct git access to the configuration (git repo hosted on only for the config). This way you could git clone the configuration, change it, git push it back and the new config will be used. This way the config would be under version control, but it would still be possible to quickly iterate on the config without changing the source repository, and would allow the Web UI/API to have access only to this configuration git repository, and not to the main code repository.

You could imagine the Workflow Editor to be similar to how you can edit & commit on - the change you make on the Web UI will still generate a commit, just like if you’d clone the repository, do your change and then push it.

You could define your trigger_map in the configuration (repository) and let to read that before triggering the build.

If the trigger map have to be read from the code repository it means that have to git clone it before it could decide whether the build should be started at all. From a security & reliability point of view it would be way better to not to clone the whole code repository just to read the trigger_map.

Storing the configuration in a hosted git repository would mean that:

  1. the reliability of retrieving the configuration would only depend on the git repository, and not on a third party where the actual code is stored
  2. more secure isolation, as this would allow to stick to our current security policy: we never access your code/repository directly, only on the Build Virtual Machines and in the way you define it (in your bitrise.yml configuration).

Keeping the configuration in a separate repository is also useful if you want to use the same code repository multiple times. If the bitrise.yml config is defined in the code repository then it’s more complicated to define multiple configurations, using the same code repository.

A point against doing this as a bitrise provided git repository: the ability to be able to send Pull Requests for configuration changes is awesome, and implementing a PR review system is not an easy task.

On the other hand, getting the configuration from the code repository directly, in a service independent way (meaning: we can’t just use the GitHub etc. API to get the configuration, without actually git clone-ing the repository) would require us to store & poll the code repository, which would be even worse than the lack of configuration PRs…

Let us know what you think about this proposal!

(PROs and CONs) Store the config in the source code repository


  • Version control
  • Relatively simple setup (if you consider writing a YML manually - without the help of the UI - simple)
  • You can use your source code hosting server’s Pull Request tools to do Pull Request reviews on the config change


  • Not possible to implement workflow mapping (trigger_map) without accessing the code before the build would start. Right now the source code repository is only accessed / cloned inside the build virtual machine.
  • Impossible to integrate it with the Workflow Editor (web UI); that would require access to the source code repository (security concern), and it couldn’t use e.g. the GitHub API either, as we have to support more than just a “few” selected Git hosting providers.
    • Possible “workaround” note (thanks to @kennethlynne): A possible workaround we would be happy with is with read only UI, so that if one wants to save a change to the bitrise file it would let us download the new config, or better yet: Create a PR for the change.
  • Not trivial to decide what to do for a branch specific trigger. E.g. if the main config has a pattern for feature/*, and you create a Pull Request on feature/a which also changes the configuration of the related workflow, should we use the config from the PR, or should we use the existing / main configuration (stored e.g. on the master branch)?
  • Doesn’t allow quick iteration of the configuration, you have to change your code (commit into your repository) to test a new configuration
  • Requires access to the code outside of the build Virtual Machine, to be able to decide whether the build should start at all.
  • Reliability: we’d depend on the source code hosting service, to be able to access the configuration.

(PROs and CONs) Store the config in a separate repository


  • Version control
  • High level overview, single config which covers what should happen on any branch / for any trigger
  • Can be integrated with the Workflow Editor (web UI), through an API would provide
  • Allows iteration of the configuration without changing the source code / commiting into the source code repository. Also allows you to use one version/revision of the code with a specific revision of the configuration. E.g. you originally build code X with configuration revision Y; if the configuration is stored in another repository you can rebuild the same build with another revision (e.g. latest) of the configuration.
  • More granular access control - you can decide who should have access to the configuration; it’s not tied to the source code access of a user.
  • Reliability: there’s no dependency on a 3rd party service to be able to read (and write) the configuration. This is especially important if you consider that someone might accidentally revoke the required access rights to the source code repository, so that won’t be able to access it anymore at all, until the issue is fixed.
  • Allows projects where you don’t have a source code repository at all, and/or where you can’t store the configuration in the source code repository for one reason or another.
  • Possibility of sharing configuration between projects; can be implemented in a way that more than one project can use the same config repository.
  • Possible to use a workaround if you want to store the config in your source code repository, the way you can do it today (see the Workaround in the meantime section below).


  • Requires additional setup, cloning the source code repository will not include the configuration automatically, you have to also clone the config repo - although that can be added as a submodule, for easier access.
  • No easy way to provide Pull Request review feature for the configuration, unless we implement one ourself

Workaround in the meantime

Definitely planned, in the meantime you can do this by using a configuration on which clones your code and then runs bitrise (the CLI) again, using the bitrise.yml from your repository.

You can find a sample configuration at: – you can just import this on (in the Workflow Editor – select bitrise.yml on the left side and just copy-paste the content & hit save).

This’ll add a bit of verbosity to your log, but this way you can define how your repository should be retrieved (if you need more than just a simple git-clone), and then it’ll use the bitrise.yml from your repository.

Of course, if you use this solution (or any solution where the code have to be cloned first) bitrise will only be able to check your trigger_map once the code is available, so every code push will trigger a build, because at that time the trigger_map is simply not yet available for bitrise to check.

Copied from original issue:


How to replicate workflows between apps

From @timotei on Thu Jun 16 2016 14:07:44 GMT-0400 (EDT)

IMO, there should still be a quick way to edit/update the .yml file directly from the Web UI, without having to go through the source code, for the reasons you mentioned: quick iterations, especially when testing some complex workflows. We can use the bitrise cli awesomeness, but it’s not always to be setup properly to emulate the CI environment. Even with a config-specific repo is a tad too much ceremony + you’ll have one more repo to “maintain”, compared to a simple “edit & save”.

What can be done is what AppVeyor also does, which is a checkbox that says “ignore bitrise.yml (from source code)”. That way you can quickly test .yml config directly from the WebUI, but you can revert to the source-based when you have properly constructed your steps and committed them.



From @viktorbenei on Fri Jun 17 2016 07:44:35 GMT-0400 (EDT)

@timotei we definitely want to choose a solution which can be supported through the Web UI. The checkbox you mentioned is one possible solution. We talked about it and the issue with it is that you can’t mix the two solution. You either have to store the code in your code repo, or define it on, it would not be possible to quickly switch between the two, e.g. to edit something quickly on the web UI then switch back to the YML mode.

Our proposal here with a hosted repository, as mentioned in the proposal, would solve this, as you’d be able to edit the config on the Web UI and through git at the same time, without any toggle. If you’d change something on the Web UI that would generate a git commit, just like how it works on the GitHub web UI (when you edit a file on GitHub web UI). And if you’d change it through git it’d be reflected in the Workflow Editor too.



From @kennethlynne on Mon Jul 11 2016 02:25:45 GMT-0400 (EDT)

We struggle with keeping branches and build configuration in sync.

Some branches might need some custom CI steps.

Changes in workflow should be reviewed, and we should be assured that the build passes before merging workflow changes into master.

We prefer having the configuration in our repo over the editor UI.

A possible workaround we would be happy with is with read only UI, so that if one wants to save a change to the bitrise file it would let us download the new config, or better yet: Create a PR for the change.



From @viktorbenei on Mon Jul 11 2016 03:29:39 GMT-0400 (EDT)

@kennethlynne for branch specific configurations you can use Workflows and the Trigger Map, I’d say that’s less of an issue - especially if you consider the use case when you want to test a new configuration on an already committed code, which you can’t do if the config is part of the code repository.

On the other hand, workflow/config reviews are indeed an important feature, and we definitely plan to solve it as part of this feature, we’re just not sure yet about the best possible way.

Personally I still think that storing the configuration in a separate repository is the best option, for the reasons explained in the “Summary and Proposal” section, as that provides enough flexibility for everyone (for you and for the Bitrise (web) service too) and proper access control too.

That said we’re still open to discuss pros & cons and other ways to provide the best feature for everyone (or at least for as many use cases as possible).



From @wrousseau on Sun Jul 24 2016 19:17:31 GMT-0400 (EDT)

Another argument is that I think that many people are coming from travis or circle ci (such as me) and first tried creating a bitrise.yml on their repo, expecting it to be taken into account. I actually even had trouble even encountering this discussion.

Maybe the transition would be easier if the file was in the same repository ?



From @viktorbenei on Mon Jul 25 2016 06:10:46 GMT-0400 (EDT)

@wrousseau good point, but there are other systems with other conventions, we’d rather find the “best” solution than to implement a feature the way it is implemented in another service, just because they decided to implement it that way. We’re simply not convinced that the way it is handled in travis / circle is the best way. That doesn’t mean that we don’t consider that as a possible solution, but we want a clear list of pros & cons.

If you can add points to either pros or cons (or both), we’d be more than happy to discuss it! I guess, easier transition might be considered as a pro, but I wouldn’t prioritise it too high.



From @viktorbenei on Mon Jul 25 2016 06:43:47 GMT-0400 (EDT)

Updated the original issue text, with PROs & CONs lists. Tried to collect & summarise all the points discussed so far here.



From @fredrikhaglund on Tue Aug 16 2016 12:11:11 GMT-0400 (EDT)

I prefer the solution where you store the complete configuration in a repo hosted by bitrise.

Please consider to put everything in there including certificates, provisioning profile, environment variables and everything else related to the configuration.

Also consider creating a tag every time a build is started so you can see which configuration was used.

If you do want to put the build process under version control in your own repo there will always be a catch 22 situation cloning the repo first. If you want to work a round that why not create a new Execute-step that points to a bitrise.yml file in the project and execute it similar to how you can trigger fastlane today? Then you have to option to just have a minimal scaffold to get the repo and trigger the build in bitrises repo and still get all the PROs of handling config in the project repo.



From @viktorbenei on Tue Aug 16 2016 12:38:57 GMT-0400 (EDT)

I agree @fredrikhaglund and I think the issue is not that it’s not possible to do today (run the config from the repo), but that it’s not obvious how and that there’s no “official” way to do it.

We’ll soon address this issue, providing a built in / guided way to store the yml in the code repo, and we also plan to provide a solution to store the configuration in a second, hosted config repo, but we don’t have an ETA for that.

Also consider creating a tag every time a build is started so you can see which configuration was used.

We’d store the config-repo-commit-hash for the build, so that every build has a link to the exact state of the config it was triggered with.

How to run bitrise.yml from your repo

We now did this for a couple of our own projects, and it seems this solution works quite good - example yml which you should import into, which clones the repo and then runs the bitrise.yml from the repo:

format_version: 1.2.0

    - activate-ssh-key:
        run_if: '{{getenv "SSH_RSA_PRIVATE_KEY" | ne ""}}'
    - git-clone: {}
    - script:
        title: continue from repo
        - content: |-
            set -ex
            bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}"
    - _run_from_repo

    - _run_from_repo

- pattern: "*"
  is_pull_request_allowed: true
  workflow: ci

With this solution, if you want to run workflow Xyz (defined in the repo!) you just have to create a workflow on with the same name (Xyz), and it will automatically get the code, and then bitrise run with the same workflow name but using the bitrise.yml defined in the repo.



From @joehanna on Thu Nov 03 2016 09:24:57 GMT-0400 (EDT)

I suggest the bitrise.yml could be implemented simply as a Github secret Gist. The build process can pull it down before doing anything else. With the appropriate permissions, could still provide an editor and save it back to the Gist. The URL/API keys for the secret Gist would be stored against the App configuration (not in the Workflow configuration).



  • It is a third party dependency at the end of the day
1 Like


From @bootstraponline on Thu Nov 03 2016 09:50:08 GMT-0400 (EDT)

> I suggest the bitrise.yml could be implemented simply as a Github secret Gist.

Secret gists are not secret. For larger companies where this matters, that solution wouldn’t work.

1 Like


From @mjracca on Thu Nov 03 2016 16:38:30 GMT-0400 (EDT)

Would definitely love if we could load the yaml from our repo, but without loosing the UI customization from the web (which is awesome!).



From @viktorbenei on Fri Nov 04 2016 12:15:45 GMT-0400 (EDT)

@joehanna awesome idea! Not sure if this should be built in, as you can already do it the way described at (except the “edit in the UI” part) - the only thing required is to drop in a wget -O bitrise.yml right before the bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}" line to download the bitrise.yml from GitHub gists.



From @viktorbenei on Fri Nov 04 2016 12:16:09 GMT-0400 (EDT)

> Would definitely love if we could load the yaml from our repo, but without loosing the UI customization from the web (which is awesome!).

@mjracca we’re working on that :wink:

1 Like


From @viktorbenei on Fri Nov 04 2016 12:24:41 GMT-0400 (EDT)

Ohh, and one more thing for everyone: for a couple of weeks now, we store the bitrise.yml for every build. You can now check it on the UI: open the Build’s page and click the “Build’s Bitrise.YML” button, right above the log:

This feature is still in “beta” right now, but I don’t think we’d remove it. Once we’re sure that this feature should remain on, we’ll add new features to it like “restore this version” to one-click restore that YML, or even “diff” against the current configuration. Right now you have to copy-paste the YML back to the editor if you want to restore it.

1 Like


From @viktorbenei on Wed Dec 21 2016 04:17:49 GMT-0500 (EST)

In the meantime we published a guide, based on the example above (, with step by step sections and details/summaries which might help:



Sorry to bring up a super old thread, but I have some thoughts. Forgive me if this is the wrong place (and probably wrong time) to voice them.

Would definitely love if we could load the yaml from our repo, but without loosing the UI customization from the web (which is awesome!).

Not super ideal, but Jetbrains does this by providing a snapshot of what that DSL (or yml file) would look like. So they idea would be that you can change via the UI then copy that code into your bitrise.yml (if the option to store bitrise.yml in repository was enabled) This seems similar to the read-only suggestions above.

Potentially after every build, the repository stored bitrise.yml would override what settings were on the web UI [e.g. env vars] This is what Jenkins does for example if you specify Parameters in a jenkinsfile, they get copied into the env variables section after a build.

IMO, there should still be a quick way to edit/update the .yml file directly from the Web UI

I agree! This was done easily on Jenkins with the replay option on the UI, which allows you to run the same build with an edited jenkinsfile



It seems like this thread has been relatively inactive @viktorbenei. I was wondering if there is any updates in terms of best practices for managing bitrise.yml files. At a minimum I want to have a revision history, so I was thinking about including this in my project’s git repo, but is there a better method today?

1 Like


Having revision history would be awesome!