github-actions-failure-taxonomylisted

# GitHub Actions Failure Taxonomy ## Purpose A consistent way to classify a failing (or non-running) GitHub Actions workflow into one root-cause class, so triage goes straight from a log line to the exact YAML fix instead of trial-and-error re-runs. This is domain knowledge about how Actions actually breaks, not generic YAML advice. ## First split: did it FAIL or never RUN? - **Never ran** (no run appears, or the job count is 0): almost always the `on:` trigger, `paths`/`paths-ignore`, `branches`/`tags` filter, or a `matrix` that expanded to nothing. Do not look for a step error. - **Ran and failed**: anchor on the platform's error string, then classify below. ## Classification matrix | Class | Fastest log signal | Root cause | Fix direction | |-------|--------------------|-----------|---------------| | Permissions / token scope | `Resource not accessible by integration`, HTTP 403 | `GITHUB_TOKEN` lacks a scope | add least-privilege `permissions:` | | Missing / misnamed secret | `secret ... not found`, empty var, auth 401 | secret undefined, wrong name, or wrong scope (repo vs env) | define/rename secret; check environment | | Matrix expansion | 0 jobs, or siblings cancelled | `matrix` typo or `fail-fast: true` | fix matrix keys; `fail-fast: false` | | Cache miss | `Cache not found for input keys` | cache key drift / never saved | stabilize `key`, add `restore-keys` | | Trigger mismatch | workflow absent from runs | `on:` / paths / branch filter | widen or correct the fil