How to Track Deployments With Environments in Bitbucket Pipelines

By Kaveh Alemi·Latchkey

The deployment key tags a step with an environment (test, staging, production) so Bitbucket tracks it and applies that environment's variables.

Add deployment: <environment> to a step. The environment must be one of test, staging, or production (or a custom one defined in repo settings).

Steps

• Define the environment under Repository settings to Deployments if it is custom.
• Add deployment: production to the deploying step.
• The Deployments view then records each release to that environment.

bitbucket-pipelines.yml

pipelines:
  branches:
    main:
      - step:
          name: Deploy to production
          deployment: production
          script:
            - ./deploy.sh --env prod

Gotchas

• Bitbucket enforces ordering: a step cannot deploy to production before staging if both exist in the pipeline.
• Deployment variables defined on the environment only resolve inside steps that name that environment.

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