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.
動作の概要
A step writes
KEY=VALUEpairs to$BITBUCKET_PIPELINES_VARIABLES_PATHThe step declares the exported variables in its
output-variableslistSubsequent 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:
- VERSIONMultiple 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_PATHReading 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_PATHNo special configuration needed in the consuming step — the variables are injected automatically.
Constraints
制約 | 値 |
|---|---|
Maximum variables per pipeline | 50 |
Maximum total size | 100 KB |
Variable name format | Letters, digits, and underscores. Can't start with a digit |
可用性 | 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 |
並行ステップ | 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 variableComplete 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トラブルシューティング
Variable is empty in consuming step:
Confirm the variable name in
output-variablesmatches exactly what was written to$BITBUCKET_PIPELINES_VARIABLES_PATHCheck 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-variableslists 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_PATHthat isn’t listed in itsoutput-variables. Add the variable name tooutput-variables
関連情報
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
この内容はお役に立ちましたか?