GitHub Actions Failure Matrix

Summarize GitHub Actions matrix job failures across runs so you can spot unstable OS/runtime axes fast.

Security Scan

This skill is internally coherent: it parses local GitHub Actions run JSON files to produce a failure-by-matrix report and does not request unrelated credentials or perform unexpected network or system operations.

Purpose & Capability

The name/description match the included script: it reads GitHub Actions run JSON and produces grouped matrix failure summaries. One minor mismatch: the SKILL.md shows examples using the `gh` CLI to collect run JSONs, but the skill does not declare `gh` as a required binary — `gh` is optional for producing the input files, while the script itself only needs bash+python3.

Instruction Scope

Instructions and the script operate on local JSON files (RUN_GLOB), filter/group jobs, and emit text or JSON. They reference only file reads and local processing, regex filters, and exit codes; there are no instructions to read arbitrary system configuration, environment secrets, or send data to external endpoints.

Install Mechanism

No install spec — instruction-only with an included script. Nothing is downloaded or written to system locations during install; runtime requires only bash and python3 which are reasonable for a shell+python script.

Credentials

The skill does not require any environment variables or credentials. It accepts many optional filter ENV inputs (regexes and output-mode flags) which are appropriate and proportional to its task. The SKILL.md examples mention `gh` for collecting JSON; if you follow those examples you'll need the `gh` CLI and any credentials it requires, but those are outside the skill's declared requirements.

Persistence & Privilege

The skill is not always-enabled and does not request persistent agent privileges or modify other skill configurations. It runs on demand and processes local JSON artifacts only.

Assessment

This script is straightforward: it analyzes local GitHub Actions run JSON files and does not exfiltrate data or require secret environment variables. Before running: 1) review or run the included script on the bundled fixture files to see the output format; 2) confirm the JSON files you point it at are from trusted sources (it will process any matching JSON file); 3) if you want the SKILL.md examples to fetch runs with `gh`, install `gh` and ensure your GitHub auth is configured separately (the skill does not manage or require GitHub credentials itself). If you need extra assurance, inspect the full script source locally (it only uses standard Python libs) before executing.

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:

RUN_GLOB='artifacts/github-actions/*.json' \
OUTPUT_FORMAT=json \
FAIL_ON_FAILURES=1 \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

Filter to a specific workflow + branch + matrix axis (for targeted triage):

RUN_GLOB='artifacts/github-actions/*.json' \
WORKFLOW_MATCH='(CI|Test)' \
BRANCH_MATCH='^(main|release/)' \
AXIS_MATCH='ubuntu-latest \| python-3\.12' \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

Isolate timeout-only matrix failures:

RUN_GLOB='artifacts/github-actions/*.json' \
CONCLUSION_MATCH='^timed_out$' \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

Exclude noisy flaky suites while keeping the rest of the matrix view:

RUN_GLOB='artifacts/github-actions/*.json' \
WORKFLOW_EXCLUDE='nightly|experimental' \
JOB_EXCLUDE='lint|docs' \
AXIS_EXCLUDE='windows-latest' \
CONCLUSION_EXCLUDE='^cancelled$' \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

Focus only on setup/toolchain breakages by failed step name:

RUN_GLOB='artifacts/github-actions/*.json' \
FAILED_STEP_MATCH='setup|install|dependency' \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

Limit triage to a specific run range or workflow URL pattern:

RUN_GLOB='artifacts/github-actions/*.json' \
RUN_ID_MATCH='^(28419|28420)' \
RUN_URL_MATCH='example/repo/actions/runs' \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

Scope triage to a commit range by headSha:

RUN_GLOB='artifacts/github-actions/*.json' \
HEAD_SHA_MATCH='^(abc123|def456)' \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

Scope triage to specific repositories when aggregating exports from multiple repos:

RUN_GLOB='artifacts/github-actions/*.json' \
REPO_MATCH='^flowcreatebot/(yf-api-saas|conspiracy-canvas)$' \
bash skills/github-actions-failure-matrix/scripts/failure-matrix.sh

Run with bundled fixtures:

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

Output contract

• Exit 0 by default (reporting mode)
• Exit 1 if FAIL_ON_FAILURES=1 and at least one failure group is found
• In text mode, prints summary + top failure matrix groups
• In json mode, prints machine-readable summary and grouped failures