GitHub Actions Failure Matrix

Use this skill to turn noisy GitHub Actions run JSON into a matrix-focused failure report.

What this skill does

• Reads one or more JSON exports from GitHub Actions runs (via gh run view --json)
• Detects failure-like matrix jobs (failure, timed_out, cancelled, etc.)
• Extracts matrix axes from common job-name patterns (name (a, b), name [a, b], name / a / b)
• Groups repeated failures by workflow + job + matrix axis signature
• Emits ranked triage output in text or json

Inputs

Optional:

• RUN_GLOB (default: artifacts/github-actions/*.json)
• TOP_N (default: 20)
• OUTPUT_FORMAT (text or json, default: text)
• FAIL_ON_FAILURES (0 or 1, default: 0) — exit non-zero when failure groups exist
• MIN_OCCURRENCES (default: 1) — hide groups below this repeat count
• WORKFLOW_MATCH (regex, optional) — include only workflows whose names match
• WORKFLOW_EXCLUDE (regex, optional) — drop workflows whose names match
• BRANCH_MATCH (regex, optional) — include only runs whose branch names match
• BRANCH_EXCLUDE (regex, optional) — drop runs whose branch names match
• JOB_MATCH (regex, optional) — include only base job names that match
• JOB_EXCLUDE (regex, optional) — drop base job names that match
• AXIS_MATCH (regex, optional) — include only parsed matrix-axis strings that match
• AXIS_EXCLUDE (regex, optional) — drop parsed matrix-axis strings that match
• CONCLUSION_MATCH (regex, optional) — include only specific failure conclusions (failure, timed_out, cancelled, etc.)
• CONCLUSION_EXCLUDE (regex, optional) — drop specific failure conclusions
• FAILED_STEP_MATCH (regex, optional) — include only jobs whose terminal failed step matches
• FAILED_STEP_EXCLUDE (regex, optional) — drop jobs whose terminal failed step matches
• RUN_ID_MATCH (regex, optional) — include only runs whose run id matches
• RUN_ID_EXCLUDE (regex, optional) — drop runs whose run id matches
• RUN_URL_MATCH (regex, optional) — include only runs whose URL matches
• RUN_URL_EXCLUDE (regex, optional) — drop runs whose URL matches
• HEAD_SHA_MATCH (regex, optional) — include only runs whose headSha matches
• HEAD_SHA_EXCLUDE (regex, optional) — drop runs whose headSha matches
• REPO_MATCH (regex, optional) — include only runs whose repository matches (repository.nameWithOwner/full_name/name)
• REPO_EXCLUDE (regex, optional) — drop runs whose repository matches

Collect run JSON

gh run view <run-id> --json databaseId,workflowName,headBranch,headSha,url,repository,jobs \
  > artifacts/github-actions/run-<run-id>.json

Run

Text report:

RUN_GLOB='artifacts/github-actions/*.json' \
TOP_N=15 \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

JSON output for CI annotation/upload: