Storing the build configuration (bitrise.yml
) in your repository can be a great idea.
It has its own PROs and CONs of course, so you have to decide it yourself
whether this solution is a good fit for your project or not.
Things to keep in mind! ⚓
You can find a discussion about what are the advantages and
disadvantages of this approach on GitHub.
To highlight a few things to keep in mind if you’d want to store and use
the bitrise.yml
from your repository:
Trigger Map is better to be managed on bitrise.io ⚓
You can of course store the trigger_map
(or Triggers
on the web UI)
in your repository (in bitrise.yml
), but if you do that you’ll lose
the ability to ignore patterns. This is because bitrise.io
have to evaluate the Trigger map before the repository would be cloned
in order to be able to avoid starting a build based on the Trigger map.
The source code is never stored on bitrise.io,
(see Code Security - Source code for more information),
so if you store the trigger map in your repository, the only way to check it
is to clone it first. Even if you prepare your trigger_map
in your repository to ignore
patterns, bitrise.io will start a build to clone
the repository, before it could abort it.
In contrast, if you specify the Trigger Map on bitrise.io, you can ignore patterns in a way that it won’t even start a build.
You can’t change the build configuration of a commit ⚓
If you use the bitrise.yml
from the repository, that means that when you
rebuild a specific commit, it will use the same bitrise.yml
every time,
the one stored in the repository for that git commit.
The only way to change the configuration is to checkout the related
branch, change the bitrise.yml
, commit the changes,
push and start a new build (rebuild of a commit won’t work,
that will always get the same bitrise.yml
, the one stored at the commit).
If you store your build configuration on bitrise.io you can always rebuild any commit with a new build configuration, the configuration is not tied to the commit / state of the repository. You can simply change a parameter and hit “rebuild”, the new build will use the latest configuration from bitrise.io.
You can’t edit the configuration in the Workflow Editor on bitrise.io ⚓
The Workflow Editor on bitrise.io can only be used to visualize and edit the configuration stored on bitrise.io.
The offline workflow editor of course can be used, so this is probably not a huge issue - and we’re working on it to make it as streamlined as possible - but might make it harder to get started (as you have to install the Bitrise CLI locally).
Pull Requests can run builds with any custom configuration ⚓
When someone sends a Pull Request they can modify the bitrise.yml
in your repository any way they like it. A recent trend for example
is to send pull requests which run a bitcoin miner, as long as
that’s possible. This can make your builds to queue, until you
abort the related build or it hits the build time limit.
Example to use bitrise.yml from the repository ⚓
There are quite a few ways to accomplish this, as all you need is:
- Define a “wrapper” build config on bitrise.io,
which defines how and from where your
bitrise.yml
will be retrieved. E.g. you could store thebitrise.yml
in a GitHub Gist too, not just in your repository. In this example we’ll use the configuration from the repository, so the “wrapper” configuration on bitrise.io will define how the repository should be retrieved. Note: this also allows more customization, for example if the repository have to be accessed through a VPN, you can configure that in the “wrapper” config and it will work. - Run the build configuration (
bitrise.yml
) with the Bitrise CLI. This is the same runner which runs any other build on the bitrise.io build virtual machines, so it’s always preinstalled and ready to be used.
The example here is really simple to setup, should work in most cases (unless you need a VPN for cloning the repository for example), but it also requires you to maintain the Trigger Map on ****bitrise.io** instead of in the repository**, as that is the recommended solution.
Step by step:
- Create an app on bitrise.io, or if you already have it registered open it.
- Go to the
Workflow
tab to open the Workflow Editor. - In the Workflow Editor switch to
bitrise.yml
mode - In the
bitrise.yml
mode:- If you already have a configuration which you want to use, download the
bitrise.yml
first, and save it into the root of your repository. There’s a button to quickly download the current_bitrise.yml_
. - Once you’re ready to replace your configuration on bitrise.io,
copy the bitrise.yml content for bitrise.io from below and paste
it into the editor on bitrise.io (in
bitrise.yml
mode of the editor)
- If you already have a configuration which you want to use, download the
- Save the changes.
bitrise.yml content for bitrise.io ⚓
---
format_version: 1.4.0
default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git
trigger_map:
- push_branch: "*"
workflow: ci
- pull_request_target_branch: "*"
workflow: ci
workflows:
_run_from_repo:
steps:
- activate-ssh-key:
run_if: ''
- git-clone: {}
- script:
title: continue from repo
inputs:
- content: |-
#!/bin/bash
set -ex
bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}"
ci:
after_run:
- _run_from_repo
another-workflow:
after_run:
- _run_from_repo
How this works: ⚓
This setup splits the build configuration into two parts:
- The “wrapper” config on bitrise.io which defines how the repository have to be retrieved (e.g. through a Git Clone), which workflows are exposed for bitrise.io builds, and defines the automatic Trigger mapping.
- Your build configuration (
bitrise.yml
), stored in your repository, which defines what should happen during the builds.
This “wrapper” configuration
defines a common workflow _run_from_repo
,
which will activate an SSH key (if specified), Git Clone the repository,
and then switch to use the bitrise.yml
from the repository
by running bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}"
.
This common workflow (_run_from_repo
) is then used through other workflows, like
ci
and another-workflow
, using the after_run
workflow chaining
mechanism. Those workflows do not have any steps, the only thing
the ci
and another-workflow
workflows do is running the
common _run_from_repo
workflow.
The trick is bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}"
.
The BITRISE_TRIGGERED_WORKFLOW_ID
environment variable is set to the
“entry” workflow, the one which started the build.
So, by running the ci
workflow, the bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}"
command will be the same as bitrise run "ci"
.
This makes it super simple and quick to expose workflows from your bitrise.yml
(stored in your
repository) to bitrise.io, all you have to do is:
- Define the workflow in your
bitrise.yml
(in your repository). - Clone the
ci
workflow (or theanother-workflow
) with a name matching the workflow in yourbitrise.yml
(in your repository), or create a new empty workflow with a matching name and add the_run_from_repo
as anafter_run
workflow. Note: in the Workflow Editor UI you can quickly clone a workflow by selecting the workflow, then clicking the “add new workflow” (_+_
) button.
Step by step usage guide of the wrapper config: ⚓
For example, to add a new deploy
workflow and to expose it for bitrise.io builds,
once you prepared your wrapper config on bitrise.io:
- Create a
deploy
workflow in your**bitrise.yml**
(in your repository, and don’t forget to commit and push thebitrise.yml
changes!) - Then create a new workflow with the same name (
deploy
) on bitrise.io - Make sure that the
deploy
workflow on bitrise.io has the_run_from_repo
as anafter_run
workflow. - Define Triggers for the
deploy
workflow on bitrise.io if you want to automate the triggering of that workflow.
Following the steps above, for example to run deploy
for every code push on master
you should
have a configuration like this on bitrise.io:
---
format_version: 1.4.0
default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git
trigger_map:
- push_branch: "master"
workflow: deploy
- push_branch: "*"
workflow: ci
- pull_request_target_branch: "*"
workflow: ci
workflows:
_run_from_repo:
steps:
- activate-ssh-key:
run_if: ''
- git-clone: {}
- script:
title: continue from repo
inputs:
- content: |-
#!/bin/bash
set -ex
bitrise run "${BITRISE_TRIGGERED_WORKFLOW_ID}"
deploy:
after_run:
- _run_from_repo
ci:
after_run:
- _run_from_repo
another-workflow:
after_run:
- _run_from_repo
This configuration will run the deploy
workflow from your repository for every
code push on the master
branch, the ci
workflow from your repository for
every code push on other branches as well as for Pull Requests,
and it will never run another-workflow
automatically, but you will be able
to start manual builds with another-workflow
, which will invoke
the another-workflow
workflow from the _bitrise.yml_
in your repository.