What is a YAML anchor?

A YAML anchor is a marker that assigns a name to a node so it can be reused later. It uses the & symbol: defaults: &defaults sets the anchor "defaults" on that node. You can then reference it with an alias *defaults. This avoids duplicating content in your YAML file.

What is the YAML merge key?

The merge key << is a special YAML feature that inserts the keys from a mapped anchor into the current mapping. For example: <<: *defaults merges all keys from the "defaults" anchor into the current object. You can override merged keys by defining them after the merge. Note: the merge key only works with mappings (objects), not sequences (arrays).

Why does my YAML alias say "unknown anchor"?

The alias references an anchor that hasn't been defined yet, or is defined in a different scope. YAML anchors must be defined before they are referenced, and they cannot cross document boundaries (--- separators). Also check for typos — the anchor name after & must exactly match the name after *.

Does GitHub Actions support YAML anchors?

GitHub Actions does support YAML anchors and aliases in workflow files. However, some CI/CD platforms strip or ignore them during processing. If anchors work locally but fail in CI, check your platform's YAML processing. Also, GitHub Actions does not support the merge key (<<) in some contexts.

YAML & Configuration

Fix YAML Anchor & Alias Reference Errors

YAML anchors (&), aliases (*), and merge keys (<<) let you reuse content. But when they break, the error messages are cryptic. Here's how to fix each type.

YAML Reuse Syntax

&anchor — define a named anchor on a node
*alias — reference (reuse) an anchor's value
<<: *alias — merge keys from a mapping anchor into the current mapping

How Anchors, Aliases, and Merge Keys Work

defaults: &defaults ← anchor named "defaults"

timeout: 30

retries: 3

production:

<<: *defaults ← merge keys from defaults

timeout: 60 ← override timeout

staging:

<<: *defaults ← merge keys from defaults

retries: 1 ← override retries

The &defaults anchor saves the mapping. The *defaults alias reuses it. The <<: merge key copies all keys from the anchor into the current mapping. Keys defined after the merge override the merged values.

Common Errors and Fixes

Error 1: Unknown Anchor

The alias references an anchor that doesn't exist or hasn't been defined yet

Invalid

production:

<<: *defaults ← anchor not defined

timeout: 60

defaults: &defaults ← defined after use!

timeout: 30

Error: found unknown anchor

Valid

defaults: &defaults ← define first

timeout: 30

production:

<<: *defaults ← use after

timeout: 60

Rule: Anchors must be defined before they are referenced. YAML parsers read top-to-bottom.

Error 2: Scope Violation

An alias references an anchor defined in a different document or scope

Invalid (cross-document)

defaults: &defaults

timeout: 30

---

production:

<<: *defaults ← different doc!

Valid (same document)

defaults: &defaults

timeout: 30

production:

<<: *defaults

Rule: Anchors cannot cross --- document boundaries. Each document is a separate scope. If you need shared data across documents, repeat the anchor in each document or restructure into a single document.

Error 3: Indentation Mismatch in Merged Content

The merge key or alias is at the wrong indentation level

Invalid (wrong indent)

defaults: &defaults

timeout: 30

production:

<<: *defaults ← same level as key

timeout: 60

Valid (correct indent)

defaults: &defaults

timeout: 30

production:

<<: *defaults ← child of production

timeout: 60

Rule: The merge key <<: must be at the same indentation level as other keys in the mapping. It's a key like any other.

Error 4: Merge Key with Non-Mapping Anchor

The merge key only works with mappings (objects), not sequences or scalars

Invalid (anchor is a list)

common: &common

- item1

- item2

production:

<<: *common ← can't merge list

Valid (anchor is a mapping)

common: &common

key1: value1

key2: value2

production:

<<: *common ← merge mapping

Rule: <<: only merges mappings. To reuse a sequence, use a plain alias *alias without the merge key.

Error 5: Parser Compatibility Issues

Some YAML parsers don't support merge keys or have different behavior

PyYAML (Python):Supports merge keys but the merged keys may not appear in the order you expect. Use ruamel.yaml for better compatibility.

js-yaml (Node.js):Fully supports anchors, aliases, and merge keys. The merged keys are added before the mapping's own keys.

GitHub Actions:Supports anchors and aliases but merge key support varies. Test your workflow before relying on <<.

Kubernetes:Supports anchors and aliases in YAML manifests. Merge keys work but can make manifests harder to debug.

Best Practices for YAML Anchors

Define anchors at the top of the file

Place all anchor definitions before their first use. This makes the structure clear and avoids "unknown anchor" errors.

Use descriptive anchor names

Name anchors after what they represent: &default-timeout, &common-logging, &base-service. Avoid &a, &b, &x — they're impossible to debug.

Keep anchors in the same document

Don't try to cross --- boundaries. If you need shared data across documents, restructure into a single document or repeat the anchor.

Prefer merge keys over full aliases for mappings

Use <<: *defaults to merge specific keys, not *defaults to replace the entire mapping. This lets you override individual keys.

Test with your actual parser

Different YAML parsers handle edge cases differently. Always validate your YAML with the same parser your application uses.

Don't overuse anchors

Anchors add complexity. If you only use a value twice, just duplicate it. Anchors are worth it when you reuse a large block 3+ times or need a single source of truth for a config value.

Frequently Asked Questions

What is the difference between alias and <<: alias?

*alias replaces the entire node with the anchor's value. <<: *alias merges the keys from the anchor's mapping into the current mapping, and you can override individual keys. Use *alias when you want an exact copy, use <<: when you want a copy with modifications.

Can I use multiple merge keys in one mapping?

Yes. You can merge from multiple anchors: <<: [*defaults, *overrides]. Later anchors override earlier ones. However, not all parsers support the list syntax. The single form <<: *defaults is more widely supported.

Why does my YAML anchor work locally but fail in CI/CD?

Some CI/CD platforms (like older GitHub Actions runners or certain Kubernetes versions) use YAML parsers that don't fully support merge keys. Test with the same parser version your CI uses. If merge keys fail, replace them with explicit key-value pairs or use a YAML preprocessor to resolve anchors before submitting.

Can I override a merged key?

Yes. Keys defined after the merge key override the merged values. For example: <<: *defaults followed by timeout: 60 will use 60 for timeout, not the value from defaults. This is the main advantage of merge keys over plain aliases.