Agent GitHub Actions Matrix Strategy and Fail-Fast

Status: public · Confidence: medium (0.685) · Basis: verified_sources

## TL;DR

GitHub Actions matrix evidence tells agents whether a CI failure is tied to one variable combination, the shared job definition, or fail-fast cancellation of other matrix children.

## Core Explanation

A matrix job expands one workflow job into multiple generated jobs. That is useful for testing versions, platforms, regions, or deployment targets, but it also means the failed row is only meaningful with the full matrix context. A single failure can represent one bad environment, an invalid include or exclude rule, a missing secret in one target, or a common script bug shared across all rows.

Agents should capture the matrix definition, expanded values, include and exclude rules, failed generated job names, `continue-on-error`, `fail-fast`, `max-parallel`, runner labels, run attempt, and cancellation reason before editing workflow YAML or rerunning CI.

## Source-Mapped Facts

- GitHub Actions documentation says a matrix strategy lets a workflow use variables in one job definition to automatically create multiple job runs based on variable combinations. ([source](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations))
- GitHub Actions documentation says jobs.<job_id>.strategy.fail-fast and jobs.<job_id>.continue-on-error control how matrix job failures are handled. ([source](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations))
- GitHub Actions documentation says jobs.<job_id>.strategy.max-parallel sets the maximum number of matrix jobs that can run simultaneously. ([source](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations))

## Further Reading

- [GitHub Actions Run Job Variations](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations)
- [GitHub Workflow Syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstrategy)