GitHub Actions now supports YAML anchors and aliases; the merge key remains unsupported

Anchors and aliases are now official

GitHub Actions workflows on GitHub.com can now use YAML anchors and aliases, and the support is written into the official documentation rather than left as folklore. According to a dev.to write-up, the reference page on reusing workflow configurations carries a section headed "YAML anchors and aliases" that explains the ampersand marker for content you want to reuse and the asterisk marker that repeats it, links the YAML specification, and gives two worked examples: sharing an env map between two jobs, and reusing an entire job configuration.

The section is recent and datable. The commit history of the documentation file in the github/docs repository reaches back to 17 September 2025, and the commit that starts it adds the heading, the opening sentence, both examples and the product condition in a single change. As the write-up is careful to note, that date fixes the documentation rather than the runtime: it says when GitHub started publishing the claim, not when any parser changed.

The product condition deserves attention. The page as a whole is published for GitHub Free, Pro and Team, for Enterprise Cloud and for Enterprise Server, but the anchors section is wrapped in a condition that selects only the first two. The documentation therefore does not claim the feature for Enterprise Server, and a workflow reused across both products should not assume anchors work on both.

What the parser does

On the implementation side, the workflow parser published in the actions/runner repository exposes a parse option named AllowAnchors. With the option off, the reader rejects an anchor on a scalar, a mapping start or a sequence start with a message along the lines of "Anchors are not currently supported. Remove the anchor 'common'". With it on, the reader records anchors by position and replays them when it meets an alias, and raises a different error for an alias whose anchor it has never seen. GitHub's pre-run validation service is not open, so the write-up does not claim which setting that service uses; it reports what the published parser offers and what the documentation states.

The merge key is a different construct

The merge key, written as <<, is not part of the same feature. Anchors and aliases are defined by the YAML parsing layer, while the merge key is a convention applied above it, so a reader can support the first two and still hand the third through as an ordinary key spelled with two angle brackets.

That is why its failure modes are confusing. The workflow root and each job are mappings with fixed properties and no loose keys, so a merge key there produces an unexpected-value error naming a key the author did not think they had written. Not every mapping is fixed, though: a workflow-level env map accepts any non-empty string as a key, so a merge key placed there is quietly accepted as the name of an environment variable. The merge key appears nowhere in the documentation and has no property in the published workflow schema.

What to use instead

The write-up recommends anchoring and aliasing whole values, such as a complete map or a complete job, which is exactly what the documented examples do; extending a map is what the merge key was for, and there is no substitute for it here. For repetition across boundaries, it points to the declared interfaces: composite actions for shared steps, and reusable workflows with workflow_call and typed inputs for shared jobs, both of which cross files and repositories and carry no product condition. Anchors are best kept for small repetitions within one file, with a comment noting the dependency so that a move to Enterprise Server is a conscious decision rather than an accident.

Why it matters

For years the correct answer to whether GitHub Actions workflows can use anchors was no, and a large body of answers and blog posts still says so. That advice is now outdated for GitHub.com and Enterprise Cloud but remains true for Enterprise Server, creating a silent divergence for teams that share workflows across products. The merge key sits in an even odder spot, rejected by name in some positions and accepted as a literal environment variable name in others. Recognising which of the three situations you are facing, stale advice, a product gate, or a construct that was never supported, is the difference between a quick fix and a long debugging session.