YAML templating
YAML Templating allows you to inject Bitbucket repository and workspace variables directly into your bitbucket-pipelines.yml using ${{VARIABLE_NAME}} syntax. This lets you parameterize pipeline configuration — such as Docker image names, cache paths, and step names — without hardcoding values.
構文
${{VARIABLE_NAME}}The double-brace syntax is evaluated at pipeline parse time (before the pipeline runs). It is distinct from runtime environment variable expansion ($VARIABLE_NAME), which occurs during script execution.
Substitution is a plain text replacement over the whole file, done before the file is parsed as YAML. It works anywhere in the file, including in files brought in with import:, which use the variables of the repository running the pipeline. Variable names can contain only letters, numbers, and underscores, and are case-sensitive. Spaces aren't allowed inside the braces, so ${{ VARIABLE_NAME }} isn't substituted.
Supported Variables
Variables from these sources are available for YAML templating:
ソース | Available Variables |
|---|---|
ワークスペース変数 | All non-secured workspace variables |
リポジトリ変数 | All non-secured repository variables |
Built-in Bitbucket variables |
Other built-in variables that are known before the pipeline starts are also available, such as |
制限事項
Secured variables cannot be used in YAML templates (they're left out, so the reference isn't substituted)
Deployment variables are not available at parse time
Runtime-defined variables (set via
$BITBUCKET_PIPELINES_VARIABLES_PATH) are not available
Supported Fields
${{...}} substitution works anywhere in a pipeline YAML file. Common uses:
フィールド | 例 |
|---|---|
|
|
|
|
|
|
Cache paths |
|
Script values |
|
Import paths |
|
Script lines still also support standard shell variable syntax ($VAR) for runtime values. Use ${{VAR}} for parse-time substitution and $VAR for runtime substitution.
例
Parameterize Docker Image
image: ${{NODE_IMAGE}}
pipelines:
default:
- step:
name: Build
script:
- npm install
- npm testWith repository variable NODE_IMAGE=node:20, the pipeline runs using node:20.
Parameterize Step Name and Deployment
pipelines:
branches:
main:
- step:
name: Deploy to ${{DEPLOY_ENVIRONMENT}}
deployment: ${{DEPLOY_ENVIRONMENT}}
script:
- ./deploy.shParameterize Cache Path
definitions:
caches:
custom-deps:
path: ${{DEPS_CACHE_PATH}}
pipelines:
default:
- step:
caches:
- custom-deps
script:
- install-depsMix Parse-Time and Runtime Variables
image: ${{BASE_IMAGE}}
pipelines:
default:
- step:
name: Build ${{APP_NAME}}
script:
- echo "Building commit $BITBUCKET_COMMIT" # Runtime variable
- echo "App: ${{APP_NAME}}" # Parse-time substitution
- npm run buildEvaluation order
Parse time:
${{VARIABLE}}substitutions are resolved from workspace/repository variables and built-in variablesRuntime:
$VARIABLEsubstitutions are resolved from environment variables within the build container
This means ${{VARIABLE}} values are baked into the pipeline structure before any step runs.
Combining with YAML anchors
Templates can be combined with anchors for powerful parameterization:
image: node:${{NODE_VERSION}}
definitions:
steps:
- step: &install
name: Install (${{NODE_VERSION}})
caches:
- node
script:
- npm ci
- step: &test
name: Test
script:
- npm test
pipelines:
default:
- step: *install
- step: *testSet NODE_VERSION=20 in repository variables and every step using the template picks it up.
トラブルシューティング
Variable not substituted (shows literal ${{VARIABLE_NAME}}):
Check that the variable is defined as a workspace or repository variable
Confirm the variable is not secured
Verify spelling matches exactly (case-sensitive)
Check that the variable's value isn't empty
Check that there are no spaces inside the braces
For a built-in variable, check that it applies to this pipeline. For example,
BITBUCKET_PR_IDonly exists in pull request pipelines
Pipeline or step fails because of an unresolved reference:
A reference that can't be resolved doesn't stop the file from being parsed. The literal
${{VARIABLE}}text stays in the file, and the pipeline or step fails later wherever that text is used. For example, a script line containing it fails with a "bad substitution" error.There's no fallback syntax. Define the variable as a workspace or repository variable with a value that isn't empty.
ベスト プラクティス
Use for structural configuration — Image tags, environment names, template URLs; not for secrets
Document required variables — Add a comment block at the top of your pipeline listing all required
${{...}}variablesProvide defaults — Set sensible default values for variables in the repository settings so pipelines work without manual configuration
Never use secured variables — Secured variables are intentionally excluded from template substitution
Version template imports — Use
${{TEMPLATE_VERSION}}in import paths to let repos control which template version they use
関連情報
Variables reference — Full variable documentation
Tutorial 6: YAML Templating — Hands-on guide
この内容はお役に立ちましたか?