4.1.3. Untangling Anchors and Matrix Expansions

💡 First Principle: The workflow you read and the workflow that ran are different documents — YAML anchors expand and matrices multiply before execution — so accurate troubleshooting requires performing that expansion mentally before you compare configuration to behavior.

For anchors (2.2.5), expansion means textual substitution: every *alias becomes a copy of its &anchor, and every <<: merge injects the anchored keys into the surrounding mapping, with locally-defined keys winning. The debugging consequence is that a change to one anchor silently changes every job that merges it — so "why did the lint job's timeout change when I edited the test job?" resolves to a shared anchor. When reading an unfamiliar workflow, find the anchors first and expand them on paper; the run's Set up job output reflects the expanded values, which is your ground truth.

For matrices, expansion means one job per combination, and GitHub names each job by its matrix values — test (ubuntu-latest, 20) — which is exactly how you correlate a failure to an axis. That naming is the diagnostic tool: if every failing job shares windows-latest regardless of Node version, the problem is platform-specific (path separators, shell differences, line endings); if failures track the runtime version instead, it's a compatibility issue. include entries that added a variable appear in the job name too, and dynamically generated matrices (fromJSON) expand from the upstream job's output, so a wrong matrix means reading that job's output first.

Re-running is where the exam's newer wording lands: you can re-run a single failed matrix job from the run page rather than the entire matrix, which is how you retry one flaky variant without paying for nineteen more. Combine that with fail-fast: false when you need the full picture before deciding what to retry.

⚠️ Exam Trap: With fail-fast: true (the default), cancelled sibling jobs are not evidence of their own failure — they never finished. Diagnosing from a cancelled variant's partial logs leads nowhere; re-run with fail-fast: false to see which variants genuinely fail.

Reflection Question: A 12-job matrix shows one failure and eight cancellations. Describe precisely what you know and don't know about the eight, and the single configuration change that would make the next run diagnostic.