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

A step writes KEY=VALUE pairs to $BITBUCKET_PIPELINES_VARIABLES_PATH
The step declares the exported variables in its output-variables list
Subsequent steps receive those variables as environment variables

Writing Variables

Append KEY=VALUE to the shared variables file:

- 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

- 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.

`output-variables` Syntax

- step:
    script:
      - echo "KEY=value" >> $BITBUCKET_PIPELINES_VARIABLES_PATH
    output-variables:
      - KEY
      - OTHER_KEY

Property	Required	Description
`output-variables`	❌	List of variable names this step exports. Must match keys written to `$BITBUCKET_PIPELINES_VARIABLES_PATH`

Variables written to $BITBUCKET_PIPELINES_VARIABLES_PATH but not listed in output-variables are not propagated to subsequent steps.

Constraints

Constraint	Value
Maximum variables per pipeline	50
Maximum total size	100 KB
Variable name format	Alphanumeric and underscores only
Availability	Only to subsequent sequential steps (not parallel, not parent)
Parallel steps	Variables written inside a parallel step are not propagated to any subsequent step — neither siblings nor sequential steps after the parallel block

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  # ❌ NOT available (Step C is a sibling parallel step)
    - step:
        name: Step E
        script:
          - echo $X  # ✅ Available
          - echo $Y  # ❌ NOT available (set in parallel step, not propagated)

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

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
Parallel steps cannot pass variables to sibling parallel steps

Too many variables error:

The 50-variable limit applies across the entire pipeline run
Combine related values into structured strings (e.g., DEPLOY_ARGS="--env staging --version 1.2.3")

Variables reference — Repository, workspace, and deployment variables
Parent/Child pipelines reference — Passing variables across pipelines
Tutorial 7: Detecting Changes — Using variable sharing for change detection

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community