YAML sharing

YAML Sharing lets you define reusable pipeline configurations in a shared repository and import them into service repositories. It eliminates duplication through two mechanisms: pipeline imports (pull shared pipeline definitions from another repository using definitions: imports: + import:) and YAML anchors/aliases (reuse blocks within a single file).

Pipeline Imports

Pipeline imports let you define pipelines once in a shared repository and use them across multiple service repositories. This is a Bitbucket Cloud Premium feature.

Shared File Setup

The shared file must start with export: true and define pipelines under definitions: pipelines::

# shared-pipelines/standard-nodejs-build.yml
export: true
definitions:
  pipelines:
    nodejs-build-and-test:
      - step:
          name: Build and Test Node.js
          image: node:20
          caches:
            - node
          script:
            - npm ci
            - npm run lint
            - npm test
            - npm run build
          artifacts:
            paths:
              - dist/**

Key elements:

export: true — required at the top for cross-repository sharing
definitions: pipelines: — where shareable pipeline definitions go (not pipelines: custom:)
Pipeline name (e.g., nodejs-build-and-test) — this is what consuming repos reference

Import Source Syntax

Declare import sources in definitions: imports: using the format:

{alias}: {repo-slug}:{branch}:{filepath}

Part	Description	Example
`{alias}`	Local alias you give this source	`shared`
`{repo-slug}`	The repository slug	`shared-pipelines`
`{branch}`	Branch or tag to import from	`main`, `v1.0.0`
`{filepath}`	Path to the YAML file in that repo	`nodejs/standard-build.yml`

definitions:
  imports:
    # Single file import
    shared: shared-pipelines:main:standard-nodejs-build.yml
    # Multiple sources
    nodejs-templates: shared-pipelines:main:nodejs/build.yml
    security-templates: shared-pipelines:main:security/scan.yml

Using `import:`

The import: key references a named pipeline from an import source. The format is {pipeline-name}@{alias}:

definitions:
  imports:
    shared: shared-pipelines:main:standard-nodejs-build.yml
pipelines:
  default:
    import: nodejs-build-and-test@shared

import: can replace any pipeline section:

pipelines:
  # Replace default pipeline
  default:
    import: nodejs-build-and-test@shared
  # Replace a branch pipeline
  branches:
    main:
      import: nodejs-build-and-test@shared
  # Replace a custom pipeline
  custom:
    my-build:
      import: nodejs-build-and-test@shared

`import:` replaces the entire pipeline

The import: key replaces the entire pipeline definition. You cannot mix import: with additional steps in the same pipeline, see the example below.

# ❌ WRONG — can't mix import with steps
pipelines:
  branches:
    main:
      import: nodejs-build-and-test@shared
      - step:
          name: Deploy   # This will NOT work
# ✅ CORRECT — use import for one pipeline, write steps explicitly for another
pipelines:
  default:
    import: nodejs-build-and-test@shared   # Feature branches: shared build only
  branches:
    main:
      - step:
          name: Build
          script:
            - npm ci
            - npm run build
      - step:
          name: Deploy
          deployment: staging
          script:
            - ./deploy.sh

Constraints

Property	Value
Required plan	Bitbucket Cloud Premium
`export: true`	Required at top of shared file
Shared definitions location	`definitions: pipelines:`
Import source format	`{repo-slug}:{branch}:{filepath}`
`import:` behavior	Replaces the entire pipeline — cannot mix with steps
Multiple sources	Supported — declare multiple aliases under `definitions: imports:`

YAML anchors and aliases

Anchors define reusable blocks within a file. Aliases reference them elsewhere.

Defining an anchor

Use &name to mark any YAML node as an anchor:

definitions:
  steps:
    - step: &install-step
        name: Install Dependencies
        caches:
          - node
        script:
          - npm ci

Using an alias

Use *name to insert the anchored block verbatim:

pipelines:
  default:
    - step: *install-step
  branches:
    main:
      - step: *install-step  # Same step, reused

Merging with `<<:`

The YAML merge key (<<:) copies all keys from an anchor, allowing selective overrides:

definitions:
  steps:
    - step: &base-test
        name: Test
        caches:
          - node
        script:
          - npm test
pipelines:
  default:
    - step:
        <<: *base-test      # Inherit all properties
        name: Unit Tests    # Override just the name
        script:             # Override just the script
          - npm run test:unit

Anchor scope

Anchors are scoped to the current YAML document.

What can be shared

Element	Via `import:`	Via Anchors
Entire pipeline definitions	✅	❌
`step` definitions	❌ (imports replace whole pipeline)	✅
`definitions.caches`	❌	✅
`definitions.services`	❌	✅
Secured variables	❌	❌

Complete example

Shared file (shared-pipelines/standard-nodejs-build.yml):

export: true
definitions:
  pipelines:
    nodejs-build-and-test:
      - step:
          name: Install and Test
          image: node:20
          caches:
            - node
          script:
            - npm ci
            - npm run lint
            - npm test
            - npm run build
          artifacts:
            paths:
              - dist/**

Consuming pipeline (payment-api/bitbucket-pipelines.yml):

definitions:
  imports:
    shared: shared-pipelines:main:standard-nodejs-build.yml
pipelines:
  # Feature branches — shared build only
  default:
    import: nodejs-build-and-test@shared
  # Main branch — shared build + deployment
  branches:
    main:
      - step:
          name: Build
          image: node:20
          caches:
            - node
          script:
            - npm ci
            - npm run build
          artifacts:
            paths:
              - dist/**
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - ./deploy.sh staging

Troubleshooting

Import not found: Verify the import source format (repo-slug:branch:filepath). Check that the shared file starts with export: true and defines pipelines under definitions: pipelines:.

Anchor not found (Alias *step-name not found): The anchor must be defined before it is referenced. Check for typos in the anchor name.

Cannot add steps after import: import: replaces the entire pipeline. Use a separate pipeline section for customized workflows.

Best Practices

Pin import branches — Reference a specific branch or tag (v1.0.0) to prevent unexpected breaking changes
Namespace anchors — Use descriptive names like &nodejs-install not &install to avoid collisions
Keep shared files focused — One file per language or tier (e.g., nodejs.yml, python.yml)
Use <<: for customization — Services can inherit shared steps and override individual properties

YAML templating reference — Parameterize shared templates with ${{VARIABLE}} syntax
Tutorial 5: YAML sharing — Hands-on guide

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