How do Bitbucket deployment environments control who ships to production?

Bitbucket deployment environments give you per environment variables, a manual Promote step, a lock of one in-progress deployment per environment, and on Premium, deployment permissions and branch restrictions. Together they decide who can ship to production and from which branch. Without Premium, some of those limits are not available.

What you get

Pipelines creates three default environments, Test, Staging and Production, which you can rename. Bitbucket says these types logically organize deployments. Place Test first, then Staging, then Production when you use several.

Manual promotion

Adding trigger: manual to a deployment step makes it wait for approval before it runs, shown as a Promote button. Promoting opens a preview of the commits and file changes about to be deployed, which is a useful last look.

- step:
    name: Deploy to production
    deployment: production
    trigger: manual
    script:
      - ./deploy.sh production

Branch restrictions

On Premium, you can limit which branches deploy to an environment, using patterns such as main, release/* or v*.*.*. Bitbucket's example allows production deployments only from main and hotfix/*. Without this, any branch whose pipeline names the production deployment can reach it, subject to your other controls.

Steps to set up a production gate

1. Name the production step with deployment: production and set trigger: manual.
2. Move production credentials into the Production deployment variables, and mark them secured. See Bitbucket variable scopes.
3. If you have Premium, restrict production to main and your release branches, and limit who may deploy.
4. Use OIDC with a trust policy bound to the deployment environment. See Bitbucket OIDC for AWS.
5. Require merge checks on main. See Bitbucket merge checks.
6. Review who has repository admin, since admins grant deployment rights.

What this does not cover

A manual step is a pause, not an approval workflow. Bitbucket's page does not describe separate approver rules. If two person approval matters, rely on merge checks before the code reaches the branch. Also note that anyone who can edit bitbucket-pipelines.yml on an allowed branch can change what the production step runs, so protect that branch.

Common mistakes

Teams often name the production deployment on a step in every branch pipeline and rely on people to remember not to run it. Others copy production credentials into repository variables for convenience, which makes them visible to every step. A third pattern is renaming environments without checking which variables moved with them. Review the pipeline file once a quarter and compare it to what your deployment settings say should be possible. Anything that can deploy but should not is a gap worth closing before it is used.

Try it yourself

Click through it at your own pace, or open it full screen. Look at how a gate sits between a change and its release.

Safeguard policies and gates add automated checks to that path, and you can try a free scan at https://gold.safeguard.sh/scan.

Quick check

Sources

• Atlassian: Set up and monitor deployments, fetched 19 October 2026.

Last reviewed: 19 October 2026.