How to Set a Variable in Bitbucket Pipelines

By Kaveh Alemi·Latchkey

Bitbucket Pipelines reads variables from the repo/workspace settings and from inline shell exports within a step.

Define non-secret config and secrets as repository, deployment, or workspace variables in settings. Within a step, normal shell export works; to cross steps, write a dotenv artifact.

Repository variable + cross-step value

A repo variable $NODE_ENV is read directly; a computed value is passed downstream via an artifact file.

pipelines:
  default:
    - step:
        name: Build
        image: node:20
        script:
          - echo "Building in $NODE_ENV"
          - echo "GIT_SHA=$BITBUCKET_COMMIT" > build.env
        artifacts:
          - build.env
    - step:
        name: Deploy
        script:
          - source build.env
          - ./deploy.sh "$GIT_SHA"

Gotchas

• Each step runs in a fresh container, so export does not persist between steps - pass values via artifacts.
• Bitbucket provides built-in vars like $BITBUCKET_COMMIT, $BITBUCKET_BRANCH, $BITBUCKET_BUILD_NUMBER.
• Define secrets as Secured repository/workspace variables so they are masked in logs.

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