YAML Anchors & Aliases
Define a value once with & and reuse it with * — less duplication, fewer mistakes.
Validate YAML that uses anchors and aliases with the YAML Validator — YAML Validator →
The idea
YAML lets you anchor a node with &name and alias it later with *name. Both refer to the same data, so you write it once.
Basic example
defaults: &base
retry: 3
timeout: 30
service_a:
<<: *base
name: api
service_b:
<<: *base
name: workerHere &base anchors the mapping, and *base reuses it. The << merge key pulls the anchored fields in.
Why use them
- Less duplication — repeat a block of config without copying it.
- One source of truth — change the anchor, every alias updates.
- Readable config — common settings live in one named place.
Common pitfalls
- Scope is per-document — anchors do not cross a
---separator. - Alias must be the whole value — you cannot write
path: *base/suffix. - Typo in the name — aliasing a name that was never anchored throws an error.
Validate before you ship
Anchors are powerful but easy to typo. Paste your YAML into the YAML Validator to confirm every alias resolves before committing.
Related guides
- YAML format example — a readable, annotated sample.
- Common YAML errors — what the messages mean and how to fix them.
- YAML indentation guide — spaces, tabs, and common errors.