Running a Bitrise.io workflow locally

When building more complicated Bitrise workflows, it is incredibly important to be able to run and verify them locally. This yields some big benefits:

1. Vastly reducing your dev loop time, since running the workflows locally is much faster than waiting for builds to spin up on Bitrise.io.
2. Allowing you to work on new workflows while not touching your actual production workflows on Bitrise.io.
3. Allowing you to work on new workflows while not consuming one of your available concurrent builds on Bitrise.io.

Bitrise offers a CLI that is easy to install and use to run workflows locally. However, the CLI does not cover any of the other goodies exposed by Bitrise.io - like the various environment variables that your workflow is likely to consume.

Emulating the complete Bitrise.io environment locally

Luckily, it doesn't take too much work to basically emulate the entire Bitrise.io environment on your own dev machine locally. All you effectively need to do is:

1. Inject the Bitrise.io-provided environment variables.
2. Run your workflow in CI mode (see --ci below)
3. Clean up all the files generated by your workflow (so that your machine stays 'clean' like a Bitrise.io machine).

I've solved this by creating two scripts:

• before.sh: A script that does the cleaning and exports the Bitrise.io environment variables that I need.
• check.sh: A script that simply echoes the environment variables (to give me some sanity before I actually run the workflow).

Example before.sh:

export GIT_REPOSITORY_URL=git@github.com:julo15/foo-repo.git
export BITRISE_GIT_BRANCH=staging
export BITRISE_BUILD_NUMBER=$((BITRISE_BUILD_NUMBER+1))

rm -rf foo-repo

Some notes:

• Important! Use source before.sh to run the script, since it exports environment variables.
• Being able to set the GIT_REPOSITORY_URL and BITRISE_GIT_BRANCH locally allows you to reference your own changes (i.e. changes not yet on your production branch), which is obviously very useful. This actually becomes critical in cases where you are writing a workflow that actually uploads and pushes changes to a repository, since you can test this on a non-production repo/branch, and don't need to make any change to point this back to the production repo/branch after you upload your bitrise.yml up to Bitrise.io.
  • If your workflow also consumes other repositories, you should similarly define environment variables for those repository URLs and branch names. One option is to put those in the application environment variables section in your bitrise.yml file.
• The BITRISE_BUILD_NUMBER value is automatically incremented by this script, which is very useful.
• The workflow I've written cloned the repo into a subdirectory. This has the benefit of being able to simply rm -rf that directory to clean things out.

Example check.sh:

echo GIT_REPOSITORY_URL is: $GIT_REPOSITORY_URL
echo BITRISE_GIT_BRANCH is: $BITRISE_GIT_BRANCH
echo BITRISE_BUILD_NUMBER : $BITRISE_BUILD_NUMBER

I run this after source before.sh to give me a bit more confidence that things are ready :).

Putting it all together

The dev loop you have effectively becomes:

$ source before.sh  # cleans things out, sets things up for the next run
$ ./check.sh        # look at the output of this so that things look good
$ bitrise --ci run myworkflow   # do the work!

Voila! You have yourself a simple set of instructions to run every time you want to retry a workflow.

The deploy-to-bitrise-io step

One additional note: Your workflow almost definitely contains the deploy-to-bitrise-io step, and this will fail locally with the instructions provided here.

This is fine, since you don't actually want this to succeed while you're writing your workflow. I just let this fail when I run locally, since this step is always the very last one, and I can still verify that the rest of my workflow works as expected.

Notes on uploading your bitrise.yml up to Bitrise.io.

If your workflow only references a single repository (i.e. you are only using $GIT_REPOSITORY_URL), then all you need to do to publish your change is copy and paste your bitrise.yml contents into your app on Bitrise.io. When you run the workflow from Bitrise.io, they will inject the correct (production) $GIT_REPOSITORY_URL value.

If your workflow references additional repositories, and the URLs to these repositories are written in your bitrise.yml file, you'll need to make sure you modify accordingly.

That's it :)

Hopefully this was useful to you. Feel free to shoot me an email if you have any questions or suggestions.