How to Use a Secured Deployment Variable in Bitbucket Pipelines

Define the secret as a secured variable on the deployment environment; it is masked in logs and only visible to steps that use deployment: for that environment.

Secured variables are write-only and masked in the build log. Defining one on a deployment environment (rather than the repository) also scopes it, so the staging step cannot read the production secret.

Steps

• Open Repository settings to Deployments and pick an environment.
• Add a variable, check Secured, and save the secret value.
• Reference it as $NAME in a step that sets deployment: to that environment.
• Never echo it; Bitbucket masks known secured values automatically.

Pipeline

pipelines:
  branches:
    main:
      - step:
          name: Deploy with secret
          deployment: production
          script:
            - curl -sf -H "Authorization: Bearer $DEPLOY_TOKEN" https://api.example.com/deploy
            - echo "Deploy triggered (token masked in logs)"

Gotchas

• Masking only matches the exact stored value; do not base64 or transform it before logging.
• A secured deployment variable is only available to steps that name that environment.
• Secured variables are write-only in the UI; you cannot read them back, only overwrite.

Related guides