How to run your build locally in Docker

Japanese translation unavailable

This page has not been translated into Japanese yet - we apologise for the inconvenience! If you’re interested in helping us out, feel free to translate any article in the jp folder of the DevCenter repository and open a PR!

このページは日本語への翻訳がまだ完了しておりません。ご不便をおかけして申し訳ございません! もしお手伝いできる方がいらっしゃれば、ご自由にjpフォルダの記事を日本語に訳していただき、PRを開いてください

To be able to run your Linux stack builds locally, you’ll need docker:

In this guide we’ll use this Bitrise Android sample project.

Large images ahead

The official Bitrise Docker images are quite large because they include a wide variety of preinstalled tools. You’ll need at least 20-25 GB free disk space!

If you’re not familiar with the Bitrise CLI you should try that first. You don’t have to master the CLI, if you know what bitrise run WORKFLOW does, that should be enough for this tutorial.

Downloading Docker images from

  1. Install docker.
  2. Make sure you have your bitrise.yml in your repository.

    You don’t have to commit it, but the file must exist in your repository’s root directory.

  3. cd into your repository’s directory on your Mac/Linux.
  4. Pull the image from its registry:

    docker pull
  5. Run the following command:

    docker run --privileged --env CI=false --volume "$(pwd):/bitrise/src" --volume "/var/run/docker.sock:/var/run/docker.sock" --rm bitrise run WORKFLOW`

    If you want to just jump into the container and experiment inside, you can replace --rm bitrise run WORKFLOW with -it bash to start an interactive bash shell inside the container. For example:

    docker run --privileged --env CI=false --volume "$(pwd):/bitrise/src" --volume "/var/run/docker.sock:/var/run/docker.sock" -it bash

    In general, if your project is an Android project but you don’t use Android NDK, to preserve precious disk space, you should use the docker image. You can find other official Bitrise docker images on our Quay page. In this example, we’re using the one.

  6. Download docker images from the Quay:

    docker pull`

    Be aware that this can take quite a bit of time, as this image is over 10 GB. If the download fails or hangs, you can restart it any time by running the same command again.

  7. Download your Bitrise build configuration (bitrise.yml) to the root directory of your repository.

    You can download your project’s bitrise.yml from the bitrise.yml tab of your Workflow Editor on

  8. In your Terminal / Command Line go to (cd) the root directory of your repository. Check if your bitrise.yml is at this location.

If you try to reproduce an issue, you should git clone your repository into a new directory, so that the directory will only contain the files which are committed into the repository! It’s a frequent reproducibility issue that you try to run the commands in your normal working directory, where you most likely have files which are not committed into your repository, for example, files which are in .gitignore.

Running your builds

Run your build with the following command:

docker run --privileged --env CI=false --volume "$(pwd):/bitrise/src" --volume "/var/run/docker.sock:/var/run/docker.sock" --rm bitrise run WORKFLOW

This command will share the current directory (the directory of your repository) as a shared volume with the docker container, and will make it available inside the container at the path /bitrise/src.