YAML Anchors, Aliases & Merge Keys

Basic anchor and alias syntax

An anchor marks a node with a name. An alias references that node later in the same document. The most common pattern is to anchor a mapping of shared defaults and merge it into several configurations:

# Define once with &anchor, reuse with *alias
defaults: &defaults
  adapter: postgres
  host: localhost
  port: 5432

development:
  <<: *defaults
  database: app_dev

test:
  <<: *defaults
  database: app_test

After parsing, both development and test contain adapter, host, port, and their own database key. Edit defaults once and every consumer updates.

Merge keys (<<:) explained

The merge key is the special key << followed by an alias. It tells the parser: copy the keys of the aliased mapping into this mapping. Sibling keys defined directly on the current mapping override the merged values:

# Aliased values can be overridden by sibling keys
defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  timeout: 60

production.timeout is 60, not the 30 from the merged defaults. The local key always wins.

Merging multiple anchors

You can merge several aliases at once by passing a sequence to the merge key. Earlier entries take precedence over later ones:

# Merge multiple anchors in priority order (left = highest)
base: &base
  region: us-east-1
  timeout: 30

retry: &retry
  retries: 5
  backoff: exponential

prod_service:
  <<: [*base, *retry]
  region: us-west-2

Final prod_service: region: us-west-2 (sibling key wins), timeout: 30 (from *base), retries: 5 and backoff: exponential (from *retry).

Anchors on scalars and lists

Anchors are not limited to mappings. Any node can be anchored, and you can substitute it with a plain alias (no merge key needed):

# Anchors work on scalars too
host: &primary "db-primary.internal"
fallback: *primary

# Anchors on sequences (arrays)
common_ports: &common_ports
  - 80
  - 443

web:
  ports: *common_ports

api:
  ports: *common_ports

The merge key (<<:) only works when the aliased value is a mapping. For lists and scalars, use a plain alias.

Docker Compose example

Compose supports anchors and merge keys directly in docker-compose.yml and compose.yaml. A common pattern is sharing environment variables across services:

# docker-compose.yml - share env across services
x-shared-env: &shared-env
  TZ: UTC
  LOG_LEVEL: info

services:
  web:
    image: app:latest
    environment:
      <<: *shared-env
      ROLE: web
  worker:
    image: app:latest
    environment:
      <<: *shared-env
      ROLE: worker

The x- prefix tells Compose to ignore the key as a service definition - it is a custom extension field that exists only to host the anchor.

GitLab CI example

GitLab pipelines use a leading . on a job name to mark it as a hidden template that is not run on its own. Combined with anchors and merge keys, this becomes a clean job-template pattern:

# .gitlab-ci.yml - DRY job definitions
.deploy_template: &deploy
  stage: deploy
  image: alpine:latest
  script:
    - ./deploy.sh

deploy_staging:
  <<: *deploy
  environment: staging
  only:
    - main

deploy_prod:
  <<: *deploy
  environment: production
  when: manual

Both deploy_staging and deploy_prod inherit the stage, image, and script, then add their environment-specific overrides.

The deep-merge gotcha

The single most common bug with merge keys: nested maps are replaced wholesale, not deep-merged. If the aliased map has a key whose value is itself a map, redefining that key on the current map drops every nested key the alias provided:

# Merge key is shallow - nested maps replace, not merge
defaults: &defaults
  database:
    host: localhost
    port: 5432

prod:
  <<: *defaults
  database:
    host: prod.db
# prod.database = { host: "prod.db" }
# port: 5432 is LOST because the whole "database" map was replaced.

If you need recursive merging, pre-process the YAML with a templating tool, or flatten the structure so every distinct value lives at its own top-level key.

What JSON loses on conversion

JSON has no native anchor or reference syntax. When you pass YAML with anchors through any YAML to JSON converter the structural sharing is expanded into duplicated objects:

# Anchors collapse during YAML to JSON conversion
defaults: &d
  retries: 3

dev:
  <<: *d
  name: dev

# Becomes JSON:
# { "defaults": { "retries": 3 },
#   "dev": { "retries": 3, "name": "dev" } }
# The shared structure is duplicated. JSON has no $ref by default.

The output is correct - just larger and harder to refactor. This is one of the strongest arguments for staying in YAML for human-edited configs. Compare side-by-side on the YAML vs JSON page.

Validate your anchors

Anchor errors (forward references, typos, unsupported merge keys) are silent in many editors. Drop your file into the YAML validator to confirm the parser sees what you expect, or use the YAML formatter to inspect the resolved output before deploying. For more advanced reuse patterns and how to share blocks across files, see the YAML syntax reference.