What is a YAML anchor?

An anchor is a label you attach to a value with &name. Later in the same document you can write *name, an alias, and the parser treats it as that same value. It is YAML's built-in way to avoid repeating a block, and it is resolved entirely by the parser before your program sees the data.

What does <<: *name mean in YAML?

It is the merge key. It copies every key of the aliased mapping into the current mapping. Keys written directly in the current mapping win over merged ones, wherever they appear. With a list, <<: [*a, *b], keys from earlier entries win over later ones. The merge key comes from YAML 1.1; YAML 1.2 dropped it from the spec, but most parsers still support it.

Can I use YAML anchors in GitHub Actions?

Yes, since GitHub added anchor and alias support to workflow files in 2025. The <<: merge key is not supported there, so you can reuse a whole value with *name but cannot merge a mapping and override one key. For reuse across files, use reusable workflows or composite actions.

Do YAML anchors work across files?

No. Anchors are local to a single YAML document, and a file with --- separators holds several documents. In GitLab CI an anchor defined in an included file cannot be used from the including file; use extends or the !reference tag instead.

What happens to anchors when YAML is converted to JSON?

They are expanded. JSON has no references, so every alias becomes a full copy of the value and merge keys become ordinary keys. Converting back gives you the repeated YAML, not the anchors.

YAML anchors

A YAML anchor is a label — &name — that marks a value so you can reuse it later in the same document with an alias, *name. The parser resolves aliases while reading, so your program receives plain data with the value repeated. Anchors are YAML's own answer to copy-paste.

defaults: &defaults # anchor the mapping
  image: node:22
  retries: 2
  timeout: 10m

unit:
  <<: *defaults # merge every key from defaults
  script: bun test

e2e:
  <<: *defaults
  timeout: 30m # local key wins over the merged one
  script: bunx playwright test

notify_on: &channels ["#ci", "#releases"]
deploy_notify: *channels # alias: the same list again

After parsing, e2e is { image: node:22, retries: 2, timeout: 30m, script: … } and deploy_notify is the same two-item list.

Three pieces

Syntax	Name	What it does
`&name`	anchor	Labels the value that follows it
`*name`	alias	Stands for the anchored value, in full
`<<: *name`	merge key	Copies the keys of an anchored mapping into the current mapping

An alias reuses a value as is. You can't change one key through a plain alias. The merge key is what lets you take a mapping and override part of it.

How merges resolve

Local keys always win. A key written in the mapping beats the same key from <<, whether it comes before or after the merge line.
Several merges: earlier wins. In <<: [*base, *gpu], a key present in both comes from base.
Merges are shallow. If defaults has env: { A: 1 } and you set env: { B: 2 } locally, the result is { B: 2 }, not both. Nested maps are replaced, not combined.
Lists can't be merged. << only works with mappings. There is no YAML syntax to append to an anchored list.

Where anchors work, and where they don't

Where	Anchors and aliases	`<<:` merge key	Reuse across files
Docker Compose	yes	yes	`include`, `extends`
GitLab CI	yes	yes	`extends`, `!reference` (not anchors)
GitHub Actions	yes (since 2025)	no	reusable workflows, composite actions
Kubernetes manifests	yes	yes	Helm, Kustomize
Helm `values.yaml`	yes	yes	values files, `_helpers.tpl`

Docker Compose pairs anchors with top-level x- keys, which Compose ignores, so you have somewhere to put a shared block that isn't a service:

x-logging: &logging
  driver: json-file
  options: { max-size: 10m }

services:
  api: { image: api:latest, logging: *logging }
  worker: { image: worker:latest, logging: *logging }

Gotchas

One document only. An anchor doesn't reach past a --- separator, or into another file.
Define before use. An alias must come after its anchor in the file.
YAML 1.2 dropped the merge key. Most parsers (js-yaml, PyYAML, Go's yaml.v3, SnakeYAML) still accept it, but a strict 1.2 parser may read << as an ordinary key.
Converting to JSON expands everything. JSON has no references, so aliases become copies and the anchors are gone for good.
Alias bombs. Nested aliases can expand exponentially (the YAML version of the "billion laughs" attack). Parsers that read untrusted YAML cap alias expansion; check that yours does.

Seeing what an anchor actually expands to

When a merged CI job does something you didn't expect, the fastest check is to look at the expanded data. Comma's free YAML to JSON converter resolves every anchor, alias and merge key so you can see exactly what the tool receives. YAML diff compares two files semantically, so refactoring repeated blocks into anchors shows no changes if you got it right. Both run in your browser, and either result can be published as a link teammates comment on.

Try it

Comma is free: unlimited reports, unlimited commenters, unlimited revision history.

Open the YAML to JSON converter →