How to Pass Artifacts Between Steps in Bitbucket Pipelines

By Kaveh Alemi·Latchkey

Bitbucket Pipelines hands files to later steps with the artifacts: keyword - the only way to share output across its isolated step containers.

List glob paths under a step's artifacts:. Bitbucket captures matching files and automatically makes them available to all subsequent steps in the same pipeline.

Produce and consume artifacts

The build step declares dist/** as artifacts; the deploy step downloads them automatically.

bitbucket-pipelines.yml

pipelines:
  default:
    - step:
        name: Build
        image: node:20
        script:
          - npm ci && npm run build
        artifacts:
          - dist/**
    - step:
        name: Deploy
        script:
          - ./deploy.sh dist/

Gotchas

Artifacts are passed downstream automatically to later steps - you do not "download" them explicitly.
Artifact paths are relative to $BITBUCKET_CLONE_DIR; absolute paths outside it are not captured.
Artifacts are kept for 14 days and capped in size - they are for handoff, not long-term storage.

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 pass Artifacts Between Steps in Bitbucket Pipelines?

List glob paths under a step's artifacts:. Bitbucket captures matching files and automatically makes them available to all subsequent steps in the same pipeline.

Produce and consume artifacts?

The build step declares dist/** as artifacts; the deploy step downloads them automatically.

References

GitHub Actions documentation