github-actions-merge-queue-health-audit_skill

Overview

This skill audits GitHub Actions merge-queue style workflows to surface reliability and latency issues before they block merges. It scores groups by failure rate, queue latency, and stale-success risk and emits an ok/warn/critical status. Use it to prioritize CI fixes and enforce optional fail-gate behavior for critical groups.

How this skill works

The skill reads exported GitHub Actions run JSON files and filters for merge-queue events (merge_group by default). It aggregates runs by repository and workflow (optionally by branch), computes metrics (failure rate, p95 queue time, age of last successful run), and combines them into a risk score. Outputs are produced as human-readable text or structured JSON and can optionally cause a nonzero exit when critical groups are found.

When to use it

• Before releases or large merges to catch CI queue/backlog problems early
• On CI health dashboards to rank workflows needing attention
• As a gate in automation to fail jobs when critical merge-queue health regressions appear
• During incident investigations to identify repositories or workflows with elevated failure rates
• When auditing historical CI data to prioritize maintenance work

Best practices

• Export run JSONs using gh run view for the time window you care about
• Tune thresholds (failure-rate, p95 queue minutes, stale-success hours) to match org norms
• Group by repo-workflow or repo-workflow-branch depending on team ownership granularity
• Set a minimum run count to avoid noisy signals from sparse data
• Use OUTPUT_FORMAT=json for integrations and text mode for ad-hoc human review

Example use cases

• Scan a local archive of GitHub Actions run JSONs to produce a ranked list of problematic merge queue workflows
• Run nightly and fail CI if any merge-queue group is critical to prevent risky merges
• Compare queue-latency trends across repositories to target runners or workflow optimizations
• Filter reports by workflow or branch with regex to focus on high-impact areas
• Replay against fixture data with a fixed NOW_ISO for deterministic testing