How do I install the Gha Failure Taxonomy skill?

Run npx skillmds@latest add sigistry/gha-failure-taxonomy in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Gha Failure Taxonomy safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Gha Failure Taxonomy?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Gha Failure Taxonomy free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Gha Failure Taxonomy?

sigistry (@sigistry) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Gha Failure Taxonomy by sigistry — Agent Skill

Name: Gha Failure Taxonomy
Author: sigistry

Gha Failure Taxonomy

This skill should be used when the user mentions "github actions failing", "CI failure", "workflow failed", "actions permission denied", "secret not found", "matrix", "cache miss", "GITHUB_TOKEN", "pipeline red", or is diagnosing a red GitHub Actions run. It provides a taxonomy of failure classes with log signals, root causes, and exact YAML fixes.

sigistry Updated Sep 17, 2026

File contents

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 filter
Checkout depth	`shallow`, missing tags, `git describe` fails	default `fetch-depth: 1`	`fetch-depth: 0`
Concurrency cancellation	`Canceling since a higher priority`	`concurrency` with cancel	expected; scope the group
Runner / tool drift	`command not found`, version mismatch	runner image or tool changed	pin `setup-*` version / runner image
OIDC / cloud auth	`sts:AssumeRoleWithWebIdentity` denied	missing `id-token: write` or trust policy	add permission; fix cloud trust
Flaky / network	timeout, ECONNRESET, passes on re-run	external instability	retry/backoff, pin mirrors

Triage checklist

Read the failing workflow file; find the failing job/step by name.
Quote the exact error line, it is the classifier.
Map to one primary class (secondary classes noted separately).
Cite the offending file:line.
Give the minimal corrected YAML with just the changed keys.

Additional Resources

Reference Files

For the full symptom → cause → fix catalog across every class, consult:

references/failure-catalog.md: each failure class expanded as log symptom → root cause → corrected YAML, covering permissions, secrets, matrix, caching, triggers, checkout depth, concurrency, runner/tool versions, and OIDC.

For the token and secret model in depth, consult:

references/permissions-and-secrets.md: the GITHUB_TOKEN permission model, least-privilege permissions: blocks, OIDC vs long-lived secrets, environment protection rules, and how secrets get masked or leaked.

---name: gha-failure-taxonomydescription: This skill should be used when the user mentions "github actions failing", "CI failure", "workflow failed", "actions permission denied", "secret not found", "matrix", "cache miss", "GITHUB_TOKEN", "pipeline red", or is diagnosing a red GitHub Actions run. It provides a taxonomy of failure classes with log signals, root causes, and exact YAML fixes.---# GitHub Actions Failure Taxonomy## PurposeA 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 filter || Checkout depth | `shallow`, missing tags, `git describe` fails | default `fetch-depth: 1` | `fetch-depth: 0` || Concurrency cancellation | `Canceling since a higher priority` | `concurrency` with cancel | expected; scope the group || Runner / tool drift | `command not found`, version mismatch | runner image or tool changed | pin `setup-*` version / runner image || OIDC / cloud auth | `sts:AssumeRoleWithWebIdentity` denied | missing `id-token: write` or trust policy | add permission; fix cloud trust || Flaky / network | timeout, ECONNRESET, passes on re-run | external instability | retry/backoff, pin mirrors |## Triage checklist1. Read the failing workflow file; find the failing job/step by name.2. Quote the exact error line, it is the classifier.3. Map to one primary class (secondary classes noted separately).4. Cite the offending `file:line`.5. Give the minimal corrected YAML with just the changed keys.## Additional Resources### Reference FilesFor the full symptom → cause → fix catalog across every class, consult:- **`references/failure-catalog.md`**: each failure class expanded as log symptom → root cause → corrected YAML, covering permissions, secrets, matrix, caching, triggers, checkout depth, concurrency, runner/tool versions, and OIDC.For the token and secret model in depth, consult:- **`references/permissions-and-secrets.md`**: the `GITHUB_TOKEN` permission model, least-privilege `permissions:` blocks, OIDC vs long-lived secrets, environment protection rules, and how secrets get masked or leaked.

Frequently asked questions