2.2.5. YAML Anchors, Aliases, and Merge Keys
💡 First Principle: Anchors and aliases are a YAML parser feature, not a GitHub feature — the file is expanded before Actions ever sees it — which explains both their power (reuse any repeated mapping) and their hard limit (they cannot reach across files).
The syntax has three pieces: &name defines an anchor, *name references it, and <<: merges a mapped anchor's keys into the current mapping.
x-defaults: &defaults # a key Actions ignores, holding shared config
runs-on: ubuntu-latest
timeout-minutes: 15
jobs:
test:
<<: *defaults # merge: inherits runs-on and timeout-minutes
steps:
- uses: actions/checkout@v4
- run: npm test
lint:
<<: *defaults
timeout-minutes: 5 # local key overrides the merged value
steps:
- uses: actions/checkout@v4
- run: npm run lint
Because expansion happens at parse time, the effective workflow is what you'd get by copy-pasting the anchored content everywhere the alias appears. That has consequences the January 2026 objectives call out explicitly in both the authoring domain and the troubleshooting domain (4.1.3): when you read a run's behavior, you must mentally expand aliases first, because the UI and the logs reflect the expanded document, not your compact source.
Anchors shine for repeated step blocks, shared env: maps, and consistent job scaffolding inside one large workflow. They are the wrong tool the moment you want the reuse to span repositories or even files — that's reusable workflows and composite actions, and choosing between the three is exactly the 4.3.2 comparison.
⚠️ Exam Trap: Anchors and aliases are scoped to a single YAML document. There is no way to anchor in one workflow file and alias from another, and no include directive in YAML. Any answer proposing cross-file anchor reuse is wrong.
Reflection Question: Anchors reduce duplication but make a workflow harder to read at a glance. Given that troubleshooting is a whole exam domain, when would you accept the duplication instead?
