Introduction

In Bitbucket Pipelines, YAML anchors are static reuse tools, not parameterized functions. You cannot pass runtime arguments directly into an anchor alias the way you call a function with parameters. The practical workaround is to combine anchors with environment variables, custom pipelines, and scripts that accept arguments.

What Anchors Actually Do

Anchors copy predefined YAML blocks.

1definitions:
2  steps:
3    - step: &build-step
4        name: Build
5        image: node:20
6        script:
7          - npm ci
8          - npm run build
9
10pipelines:
11  branches:
12    main:
13      - step: *build-step

The alias *build-step is textual reuse. It cannot receive an argument value on invocation.

Simulate Parameters with Variables

A common pattern is to keep step structure in an anchor and pass behavior via variables consumed by scripts.

1definitions:
2  steps:
3    - step: &deploy-step
4        name: Deploy
5        image: alpine:3.20
6        script:
7          - ./deploy.sh "$DEPLOY_ENV"
8
9pipelines:
10  branches:
11    main:
12      - step:
13          <<: *deploy-step
14          deployment: production
15          variables:
16            DEPLOY_ENV: "prod"
17    develop:
18      - step:
19          <<: *deploy-step
20          deployment: test
21          variables:
22            DEPLOY_ENV: "dev"

The step is reused, while variable values drive environment-specific behavior.

Use Custom Pipelines for Manual Runtime Input

For manual runs, custom pipelines can ask for variables.

1pipelines:
2  custom:
3    deploy-with-env:
4      - variables:
5          - name: DEPLOY_ENV
6            default: dev
7      - step:
8          name: Deploy Custom
9          image: alpine:3.20
10          script:
11            - ./deploy.sh "$DEPLOY_ENV"

This gives operator-controlled input without pretending anchors are parameterized functions.

Move Conditional Logic into Versioned Scripts

Keep pipeline YAML simple and push branching logic into scripts where testing is easier.

1#!/usr/bin/env bash
2set -euo pipefail
3
4env_name="${1:-dev}"
5
6case "$env_name" in
7  dev|staging|prod)
8    echo "Deploying to $env_name"
9    ;;
10  *)
11    echo "Unsupported env: $env_name" >&2
12    exit 1
13    ;;
14esac

This approach is easier to lint and unit test than deeply nested YAML conditions.

Security and Validation Practices

Treat input variables as untrusted until validated.

• allow-list valid environment values,
• keep secrets in secured repository variables,
• avoid echoing sensitive values to logs,
• fail fast on missing required variables.

For clarity, document required variables near each anchored step definition.

Keep Reuse Readable

Overusing anchor merges can make pipeline files hard to debug. Good practice:

• one anchor for build base,
• one anchor for test base,
• one anchor for deploy base,
• minimal per-branch overrides.

If a step needs many conditional branches, it probably belongs in script code rather than YAML structure.

Branch-Specific Overrides with Minimal Duplication

When branch behavior differs slightly, keep shared anchor content and override only small fields per branch.

1definitions:
2  steps:
3    - step: &test-step
4        name: Test
5        image: python:3.11
6        script:
7          - pytest -q
8
9pipelines:
10  branches:
11    main:
12      - step:
13          <<: *test-step
14          name: Test Main
15    feature/*:
16      - step:
17          <<: *test-step
18          name: Test Feature

This pattern keeps pipelines readable while still allowing small contextual customization.

Validate Pipeline Configuration Early

Pipeline errors are easier to fix before merge. Use linting and dry-run style checks where available, and keep a tiny validation pipeline that runs syntax and script argument checks only. Fast feedback prevents deployment-stage surprises. Consistent validation also reduces rollback frequency. It improves confidence before manual approvals. Teams benefit from faster issue triage.

Common Pitfalls

• Expecting YAML anchors to accept arguments dynamically.
• Embedding business logic in complex nested merge blocks.
• Mixing secret and non-secret variables in plain text output.
• Reusing anchors without documenting required variable contracts.
• Allowing free-form deployment targets without validation.

Summary

• Bitbucket YAML anchors are static reuse, not parameterized templates.
• Simulate arguments through environment variables and custom pipelines.
• Keep reusable structure in YAML and branching logic in scripts.
• Validate variable inputs and separate secret handling.
• Favor readable, shallow anchor patterns for maintainability.