Set up or run parallel steps

Parallel steps enable you to build and test faster, by running a set of self-contained steps at the same time.

Before you begin

  • The maximum number of parallel steps per account on a Free plan is 10.

  • The total number of parallel steps you can have in a pipeline on a Standard or Premium plan is 100.

  • All environments in a parallel step set must be of the same type, so don’t try to mix production and test environment types in the same set.

  • The total number of build minutes used by a pipeline will not change if you make the steps parallel. You'll be able to see results sooner but the total build minutes used will calculate based on the total time taken on each step.


There are several ways in which you can use this feature, however, we recommend to follow these guidelines:

  1. Set an initial step to build the software.

  2. Add a set of parallel steps to test the software.
    If you are doing a single build step leading to multiple parallel testing steps, cache external build dependencies as much as possible in the first step, so you don't waste time doing it in each of your testing steps. Then, run all your tests concurrently, they can use the cache.

  3. Deploying to multiple similar environments at the same time.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 pipelines: default: - step: # non-parallel step script: - ./ - parallel: # these 2 steps will run in parallel steps: - step: script: - ./ --batch 1 - step: script: - ./ --batch 2 - step: # non-parallel step script: - ./

Failing fast

To get faster feedback and save build minutes, you can configure parallel steps to stop immediately if any step fails. Set fail-fast: true on the parallel property to force all the running steps in the group to stop if a single step fails, such as:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 pipelines: default: - step: script: - ./ - parallel: fail-fast: true steps: - step: script: - ./ --batch 1 - step: script: - ./ --batch 2

fail-fast can also be applied to a single step:

  • If a step has fail-fast: false, then the step can fail without the whole parallel group stopping.

  • If a step has fail-fast: true, then the whole parallel group will stop if the step fails.

For example:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 pipelines: default: - step: script: - ./ - parallel: steps: - step: fail-fast: true script: - ./ - step: script: - ./

Default variables

If you want to do some fancy logic in your scripts, the following variables are available during the parallel steps:

  • BITBUCKET_PARALLEL_STEP - zero-based index of the current step in the group, e.g. 0, 1, 2, …

  • BITBUCKET_PARALLEL_STEP_COUNT - total number of steps in the group, e.g. 5.

Producing artifacts with parallel steps

Parallel steps can produce and consume artifacts, however, keep in mind the following:

  • Parallel steps can only use artifacts produced by previous steps, not by steps in the same parallel set.

  • Steps after the parallel set will get a combination of all files produced.

  • If parallel steps produce artifacts containing a file at the same location, conflicts are resolved on a per-file basis, the files generated by the latest step in the YAML file will win.

Additional Help