Variable sharing

Variable Sharing enables you to pass data between steps within the same pipeline run. A step writes exported variables to a shared file; subsequent steps read them as environment variables. This solves coordination problems like passing a computed version number or a build artifact path from one step to the next.


How It Works

  1. A step writes KEY=VALUE pairs to $BITBUCKET_PIPELINES_VARIABLES_PATH

  2. The step declares the exported variables in its output-variables list

  3. Subsequent steps receive those variables as environment variables


Writing Variables

To share a variable with later steps, append a KEY=VALUE line to $BITBUCKET_PIPELINES_VARIABLES_PATH, then list the key under the step’s output-variables.

This step builds a version string from the date and build number, and shares it as VERSION:

- step: name: Generate Version script: - export VERSION=$(date +%Y%m%d)-$BITBUCKET_BUILD_NUMBER - echo "VERSION=$VERSION" >> $BITBUCKET_PIPELINES_VARIABLES_PATH output-variables: - VERSION

Multiple Variables

To share several values, write one KEY=VALUE line for each and list every key in output-variables. This step shares the version, a short commit hash, and the path to the build artifact:

- step: name: Collect Build Info script: - export VERSION=$(cat version.txt) - export GIT_SHA=$(echo $BITBUCKET_COMMIT | cut -c1-8) - export ARTIFACT_PATH="dist/app-${VERSION}.tar.gz" - echo "VERSION=$VERSION" >> $BITBUCKET_PIPELINES_VARIABLES_PATH - echo "GIT_SHA=$GIT_SHA" >> $BITBUCKET_PIPELINES_VARIABLES_PATH - echo "ARTIFACT_PATH=$ARTIFACT_PATH" >> $BITBUCKET_PIPELINES_VARIABLES_PATH output-variables: - VERSION - GIT_SHA - ARTIFACT_PATH

Reading Variables

Variables declared in output-variables are automatically available as environment variables in all subsequent steps:

- step: name: Deploy script: - echo "Deploying version $VERSION (commit $GIT_SHA)" - ./deploy.sh $ARTIFACT_PATH

No special configuration needed in the consuming step — the variables are injected automatically.


Constraints

Constraint

Value

Maximum variables per pipeline

50

Maximum total size

100 KB

Variable name format

Letters, digits, and underscores. Can't start with a digit

Availability

All steps that start after the writing step finishes, including steps in or after a parallel block. Not available to child pipelines unless passed with input-variables:

Parallel steps

Variables written in a parallel step are available to steps after the parallel block. Steps in the same parallel block usually start together, so don’t rely on reading a sibling step’s variables. Each output variable name must be unique within a parallel block

Overwriting and precedence

If a later step writes a variable that already exists, the new value replaces the old one. Output variables take priority over workspace, repository, and deployment variables with the same name, and over variables entered when running a custom pipeline. Some built-in variables, such as BITBUCKET_PIPELINES_VARIABLES_PATH, can’t be overridden.


Availability by Step Order

pipelines: default: - step: name: Step A script: - echo "X=hello" >> $BITBUCKET_PIPELINES_VARIABLES_PATH output-variables: - X - parallel: - step: name: Step B (parallel) script: - echo $X # ✅ Available (Step A ran before this parallel block) - step: name: Step C (parallel) script: - echo "Y=world" >> $BITBUCKET_PIPELINES_VARIABLES_PATH output-variables: - Y - step: name: Step D (parallel) script: - echo $Y # ❌ Don't rely on this (Step D usually starts at the same time as Step C) - step: name: Step E script: - echo $X # ✅ Available - echo $Y # ✅ Available (Step C finished before Step E started)

Passing Variables to Child Pipelines

Variables set via output-variables are not automatically passed to child pipelines. Pass them explicitly via input-variables: on the type: pipeline step:

- step: name: Compute Version script: - echo "VERSION=$(cat version.txt)" >> $BITBUCKET_PIPELINES_VARIABLES_PATH output-variables: - VERSION - step: name: Deploy type: pipeline custom: deploy input-variables: APP_VERSION: $VERSION # Explicitly pass the variable

Complete Example: Build → Test → Deploy

This example builds a Node.js app, saves the artifact path and build time as output variables, and uses them in later test and deploy steps. The Test and Deploy steps don’t need any extra configuration to read the variables.

image: node:20 pipelines: default: - step: name: Build script: - npm ci - npm run build - export ARTIFACT=$(ls dist/*.tar.gz | head -1) - echo "ARTIFACT=$ARTIFACT" >> $BITBUCKET_PIPELINES_VARIABLES_PATH - echo "BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> $BITBUCKET_PIPELINES_VARIABLES_PATH output-variables: - ARTIFACT - BUILD_TIME artifacts: - dist/** - step: name: Test script: - 'echo "Testing artifact: $ARTIFACT"' - npm test - step: name: Deploy to Staging deployment: staging script: - echo "Deploying $ARTIFACT (built at $BUILD_TIME)" - ./deploy.sh $ARTIFACT staging

Troubleshooting

Variable is empty in consuming step:

  • Confirm the variable name in output-variables matches exactly what was written to $BITBUCKET_PIPELINES_VARIABLES_PATH

  • Check that the writing step completed successfully before the consuming step ran

  • Steps in the same parallel block usually start together, so a sibling step’s output variables may not be available yet. Move the consuming step after the parallel block

Too many variables error:

  • The 50-variable limit applies across the entire pipeline run

  • The limit is checked twice. When the YAML is parsed, the output-variables lists across all steps can't total more than 50 ("This pipeline contains more than the maximum 50 output variables allowed"). While the pipeline runs, the stored values can't exceed 50 variables or 100 KB in total.

  • Combine related values into structured strings (e.g., DEPLOY_ARGS="--env staging --version 1.2.3")

Variable not defined in output variables error:

  • The step wrote a variable to $BITBUCKET_PIPELINES_VARIABLES_PATH that isn’t listed in its output-variables. Add the variable name to output-variables


Still need help?

The Atlassian Community is here for you.