How to Use Parallel Steps with Caches in Bitbucket Pipelines

By Kaveh Alemi·Latchkey

Parallel steps each pull the shared cache, so concurrency does not mean cold installs.

Group steps under parallel to run them at once. Add caches: to each step so every parallel branch restores dependencies instead of reinstalling from scratch.

Fan out tests with a shared cache

Each parallel step declares the node cache so installs are warm.

pipelines:
  default:
    - parallel:
        - step:
            name: Unit
            caches:
              - node
            script:
              - npm ci
              - npm run test:unit
        - step:
            name: Lint
            caches:
              - node
            script:
              - npm ci
              - npm run lint

Notes

• The node cache is predefined; declaring it in each step restores ~/.npm or node_modules per Bitbuckets cache rules.
• Parallel steps consume build minutes concurrently, so plan minute budgets accordingly.

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.

# 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

Related guides

References

• GitHub Actions documentation