How to test a workflow locally, including git clone and signing

I am aware of the Bitrise cli tool to test steps and workflows locally.
But the docs are referring to the fact that you can download your existing workflow from and then test this locally. However, I did this, and it’s not working.
This is not so strange because my first step for example is activate-ssh-key point to getenv "SSH_RSA_PRIVATE_KEY" which does not exists locally. Furthermore, when it comes so signing the ios/android app, also the certificates the step refers to are not there (or at least I think, because I never got so far).
Also steps as cache-push and cache-pull how can they know where to get things?
So there are things missing. Any idea?

1 Like

Hi @stefandevogelaere,

What’s the issue on what you want to test locally?

In general, we mark steps with run_if: .IsCI (example: which are probably not required to run when you run the build/steps locally on your Mac. The SSH and the Git Clone steps are marked with this for example, as you most likely already have the source code locally, so it’d be useless to run those, as well as you’d have to provide additional configs (like an SSH key for the Activate SSH Key step).

You can of course run these steps locally if you really want to, but usually it’s not required and would require additional configuration / params, that’s why those are skipped in local by default. If you want to run these steps, simply provide the -ci flag for bitrise, or set the CI env var to true.


bitrise -ci run WORKFLOW


export CI=true
bitrise run WORKFLOW

Another solution if you only want to run one or more specific steps locally, is to overwrite the run_if statement of the step in your bitrise.yml. Every step property can be overwritten in the bitrise.yml, so instead of just

    - git-clone@3.4.3:
        title: Git Clone

you can specify run_if: true for the step:

    - git-clone@3.4.3:
        title: Git Clone
        run_if: true

As for:

You simply should not run this step locally, unless you have a very specific reason to do so. It’d probably be a bad idea to overwrite files on your Mac/PC with the cache from

These steps can of course still run, as there’s absolutely no magic involved, as long as you provide the required params of the steps as env vars the steps will run. But for these types of steps which don’t make sense on your Mac/PC I’d suggest you to simply skip those (e.g. with a run_if: false) if required.

So, in short, if you want to force a step to run which has a run_if, simply overwrite the run_if in your bitrise.yml, or fulfil the expression (by setting the CI env var, or if the run_if specifies a specific env var key then set that).

I hope this provides the information you wanted, if not or if I misunderstood something just let us know!

Thanks for the clear answer. I just thought I could create an empty folder and run the bitrise completely locally to test a “clear” environment. With the guidance you gave me, I will be able to do so. Thanks!
I even thought on running this inside a docker on my mac, but I learned that the osx boxes don’t come in docker containers, only the Java/Android ones. Would it be possible to do this? Create exact Xamarin stack as on Bitrise and run things in a docker environment? Because that would give me a 100% clone before I need to go to the cloud and locally to see what is going wrong.
Same thing goes for the certificates; of course I can import these on my local machine, but if I dockerize it, these should be in the docker as well.

1 Like

You can only run Linux inside docker, as well as there’s no legal way to distribute macOS in any way AFAIK. The macOS stacks are not docker images, those are traditional virtual machines / images in our private cloud.

If you know about any solution for this we’d be happy to discuss! Right now we have a tool in alpha which might help in the future (, which creates a base macOS vm using an installer you provide, and planned to be able to provision it after that the way our VMs are provisioned. Not the fastest solution, but without the ability to distribute macOS VMs (or macOS in any form) it’s our best idea right now.

1 Like

Hey Viktor,
the answer here is from quite some tome ago. I am interested if there are any news on this topic, to have a replica of the bitrise vm running in docker on a mac?

Hi @davormaric_zoi! This isn’t something we’re looking at at the moment. Do note that Docker can only be used to run Linux containers. That said, our stack images are public and could be recreated:

1 Like