GitHub Actions Merge Queue Health Audit

Audit GitHub merge queue workflow health with failure-rate, queue-latency, and stale-success risk scoring.

Security Scan

The skill is coherent with its stated purpose (it analyzes local GitHub Actions run JSON files) and does not request unexplained credentials or installs; minor docs mismatch about the gh CLI is the only notable issue.

Purpose & Capability

Name/description promise (audit merge-queue health) matches the included script which parses GitHub Actions run JSON and computes failure/latency/stale-success metrics. Required binaries (bash, python3) are reasonable for the shipped script. One mismatch: SKILL.md shows a 'gh run view' command to collect run JSONs, but 'gh' is not listed in required binaries—this is a documentation/metadata inconsistency (the core script itself does not invoke the GitHub CLI).

Instruction Scope

Runtime instructions and the script are narrowly scoped: they read local JSON files (RUN_GLOB), filter/aggregate runs, and produce text or JSON reports and an optional exit code. The instructions do not direct the agent to read arbitrary unrelated system files, nor to send data to external endpoints. The only network action present in docs is the suggested use of 'gh run view' (a user-invoked step to fetch run JSONs); the shipped code itself performs no network I/O.

Install Mechanism

No install spec; this is instruction-only plus a shell script. Nothing is downloaded or written to disk by an installer. Risk from install mechanism is low.

Credentials

The skill declares no required environment variables or credentials and the script only reads variables that control filtering/thresholds and a RUN_GLOB path. Requested environment access is proportionate to the stated auditing task.

Persistence & Privilege

The skill does not request permanent presence (always:false) and does not modify agent/system configuration. It only runs when invoked and uses local data; persistence/privilege concerns are minimal.

Assessment

This skill appears to do what it claims: parse local GitHub Actions run JSON files and score merge-queue health. Before installing/using it: (1) Note the SKILL.md examples use 'gh run view' to fetch JSONs — the script itself doesn't call 'gh', so install metadata should list 'gh' if you plan to follow that workflow. (2) The script reads whatever files match RUN_GLOB, so ensure that glob points only to exported run JSONs (avoid pointing it at directories with sensitive files). (3) Review the script if you need stricter validation of input JSONs or want it to fetch run data directly (that would require network access and GitHub credentials). (4) Run the provided fixtures first to verify output and behavior (the script supports NOW_ISO and fixtures for reproducible runs).

Use this skill to catch unhealthy merge_group (or pull-request gate) workflows before queue times and failures block merges.

What this skill does

• Reads GitHub Actions run JSON exports
• Focuses on merge queue style events (merge_group by default)
• Aggregates health by repo/workflow (or repo/workflow/branch)
• Scores risk using failure rate, queue latency, and stale-success age
• Emits ok / warn / critical with optional CI fail gate

Inputs

Optional:

• RUN_GLOB (default: artifacts/github-actions/*.json)
• TOP_N (default: 20)
• OUTPUT_FORMAT (text or json, default: text)
• GROUP_BY (repo-workflow or repo-workflow-branch, default: repo-workflow)
• NOW_ISO (optional ISO timestamp override for deterministic replay)
• EVENTS (comma list, default: merge_group)
• WARN_FAILURE_RATE (0..1, default: 0.2)
• CRITICAL_FAILURE_RATE (0..1, default: 0.4)
• WARN_P95_QUEUE_MINUTES (default: 8)
• CRITICAL_P95_QUEUE_MINUTES (default: 20)
• WARN_STALE_SUCCESS_HOURS (default: 18)
• CRITICAL_STALE_SUCCESS_HOURS (default: 48)
• MIN_RUNS (default: 3)
• WORKFLOW_MATCH / WORKFLOW_EXCLUDE (regex, optional)
• BRANCH_MATCH / BRANCH_EXCLUDE (regex, optional)
• REPO_MATCH / REPO_EXCLUDE (regex, optional)
• EVENT_MATCH / EVENT_EXCLUDE (regex, optional)
• FAIL_ON_CRITICAL (0 or 1, default: 0)

Collect run JSON

gh run view <run-id> \
  --json databaseId,workflowName,event,headBranch,status,conclusion,createdAt,runStartedAt,updatedAt,url,repository \
  > artifacts/github-actions/run-<run-id>.json

Run

Text report:

RUN_GLOB='artifacts/github-actions/*.json' \
bash skills/github-actions-merge-queue-health-audit/scripts/merge-queue-health-audit.sh

JSON output + fail gate:

RUN_GLOB='artifacts/github-actions/*.json' \
OUTPUT_FORMAT=json \
FAIL_ON_CRITICAL=1 \
bash skills/github-actions-merge-queue-health-audit/scripts/merge-queue-health-audit.sh

Run against bundled fixtures:

NOW_ISO='2026-03-08T00:00:00Z' \
RUN_GLOB='skills/github-actions-merge-queue-health-audit/fixtures/*.json' \
bash skills/github-actions-merge-queue-health-audit/scripts/merge-queue-health-audit.sh

Output contract

• Exit 0 in report mode (default)
• Exit 1 when FAIL_ON_CRITICAL=1 and one or more groups are critical
• Text mode prints summary + ranked risk groups
• JSON mode prints summary + ranked groups + critical groups