How to Run Parallel Steps in Bitbucket Pipelines

By Daniel Zoghalchali·Latchkey

The parallel: key runs a group of steps simultaneously, so independent checks finish in the time of the slowest one.

Wrap a list of steps in parallel:. Each runs in its own container concurrently; the pipeline waits for all of them before continuing.

Lint and test in parallel

Both steps start at once and consume separate build minutes.

bitbucket-pipelines.yml

pipelines:
  default:
    - parallel:
        - step:
            name: Lint
            script:
              - npm ci && npm run lint
        - step:
            name: Unit tests
            script:
              - npm ci && npm test

Gotchas

Parallel steps each run in a fresh container, so each reinstalls dependencies - cache them.
Parallel steps cannot depend on each other; share results downstream via artifacts.
Each parallel step counts toward your build-minute usage independently.

Verify it actually works

Bitbucket validates bitbucket-pipelines.yml on push, and a schema error disables the pipeline rather than failing a build, which can look like nothing happened at all.

Terminal

# validate before pushing
curl -X POST -H "Content-Type: application/x-yaml" \
  --data-binary @bitbucket-pipelines.yml \
  https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/pipelines/validate

# confirm which pipeline definition matched
# Pipelines -> the run -> "Configuration" tab

Constraints that catch people out

Each step runs in a fresh container. Nothing persists between steps unless it is declared as an artifact or a cache.
The default memory allocation per step is limited, and service containers share that budget, so adding a database service can push a previously passing build into an out-of-memory failure.
Only branches with a matching branches: definition run; a push to an unmatched branch silently runs nothing.
Artifacts are passed forward only to later steps in the same pipeline, not between pipelines.

Frequently asked questions

How do I run Parallel Steps in Bitbucket Pipelines?

Wrap a list of steps in parallel:. Each runs in its own container concurrently; the pipeline waits for all of them before continuing.

Lint and test in parallel?