Move your Bitrise config to Github

Debug workflows locally and own your CI configuration

Photo by Ricardo Gomez Angel on Unsplash

There are three main reasons why you’ll want to host your Bitrise config definition file with the rest of your project on a repository:

Versioning

When the CI config file is stored in your project’s repository it’s easier to track modifications and propose changes to your workflows.
The alternative is to modify workflow configurations directly on bitrise.io with little visibility of what the changes are and difficulty to rollback problematic changes

Run workflows locally

Storing your bitrise.yml in your project’s repository opens the gate for executing workflows locally. This is extremely important for any serious debugging and it’s very easy to set up. We’ll see how in a moment.

More powerful options

“Bitrise is a collection of tools and services to help you with the development and automation of your software projects”. And what you can do with the web Workflow Editor is not all there is. You need to be able to modify your bitrise.yml directly if you want to access all the features Bitrise has to offer. We’ll see an example of this at the end.

These are the three steps you need to take in order to run and debug Bitrise’s workflows locally:

1. Download the bitrise.yml file and push it to your main branch

In bitrise.io go to the bitrise.yml tab in the Workflow Editor section and select Store in app repository.

Bitrise will try to find a bitrise.yml file in your repository’s main branch and, if this is the first time you’re doing this, will fail. It’s normal.

What you’ll see is something like the image below: a message asking you to download the bitrise.yml stored in bitrise.io and add it to your project’s root directory

Once the new file is pushed to your repository click the Update settings button

⭐️ With this little change, you already achieved the first point from the reasons to migrate list: versioning. Now you can makes changes to bitrise.yml and have a clear history of them.

⚠️ Problem: if you stop here you won’t be able to use the handy online step editor to modify your workflows.

2. Install Bitrise CLI

“Bitrise_CLI is a Command Line Interface for running your Workflows from Bitrise on your local machine”

The cool thing here is that bitrise cli is the exact same tool Bitrise.io uses to run your builds remotely. When you run a workflow remotely what Bitrise does under the hood is spin up a machine with bitrise cli installed and execute the same commands you can execute locally on your development machine.

Installing bitrise cli with Homebrew can’t be simpler:

brew update && brew install bitrise

⭐️ Now you can already execute workflows locally. Let's say you have a workflow called “verify” you can trigger it with bitrise run verify on your project’s root folder

3. Install Workflow Editor web UI locally

Bitrise’s workflow editor is great to visualise your workflow, add new steps and discover the available options the are. And you can use it locally too

1. Install Go on your machine: brew install go
2. Run bitrise setup . This will install the local workflow editor and some Bitrise plugins and toolkits
3. Run bitrise :workflow-editor from your project’s root path. Something like this will pop up if everything went well

⭐️ From here you can work with workflows in the same way you’re used to from bitrise.io website. Searching for new steps works too. Any changes you do will automatically update your local bitrise.yml config

Now you can edit your bitrise.yml manually or using the handy Workflow Editor. Editing it manually has some advantages as we discussed before: there are some interesting options that aren’t available through the web editor.

run_if

For example, the run_if expression determines when a Step should run.

With the Workflow Editor you can mark a Step to run even if the previous failed but what if you want it to run only if the previous failed?

This is very handy to send notifications only for failed jobs or when a certain value is produced by a step and can’t be done through the web interface.

run_if has many options that you can set by editing the configuration file manually

• run_if: .IsBuildFailed : runs the step only if the build failed
• run_if: .IsCI : runs the step only if we are in a CI environment
• run_if: {{getenv "TEST_KEY" | eq "some value"}} : runs the step only if this expression is true

⚠️ Secrets

There is a big unsolved problem with this setup: what about your remote stored secrets? As you may have noticed we never downloaded them and the local workflow editor has no way to read them from bitrise.io

When you run workflows locally secrets are read from a .bitrise_secrets.yml file on your project’s root path

There is no option to download all your secrets in one go from bitrise.io so you’ll need to create the file yourself and manually copy the secrets you need to debug your workflow locally. It should look something like this:

- SECRET_KEY: secret key value
  opts:
    meta:
      is_expose: true

🛑 Make sure you never push this file to your repository 🛑

My recommendation here: add only the secrets you need to debug your workflow and delete the file once you’re done

If you want to chat about CI setups (who doesn’t?) feel free to reach me out on Twitter at @lgvalle

✈️ And if you are passionate about these things, at TravelPerk we are looking for Senior Android Engineers in Barcelona, London or Berlin to help us build awesome stuff.