GitHub Actions Failure Hour Audit

Audit GitHub Actions failure timing by day/hour to surface recurring outage windows and staffing hotspots.

Security Scan

The skill is internally consistent for analyzing local GitHub Actions JSON exports and does not request unrelated credentials or perform network exfiltration; note the README suggests using the GitHub CLI ('gh') to collect artifacts but 'gh' is not declared as a required binary.

Purpose & Capability

The name/description match the implementation: the included bash+python script scans local GitHub Actions run JSON files, filters failures, buckets by day/hour, ranks windows, and emits text/JSON. One minor mismatch: SKILL.md shows an example 'gh run view ... > artifacts/..' to collect run JSONs, but the skill metadata/bins do not list the GitHub CLI ('gh'). That is a documentation/inventory inconsistency (the script itself does not invoke 'gh').

Instruction Scope

Runtime instructions and the script operate only on local JSON files matched by RUN_GLOB and environment-configurable filters. The script reads file contents, computes metrics, and prints text/JSON; it does not perform network calls, modify system configuration, or access unrelated files. The only scope extension is the SKILL.md example which instructs the user to use 'gh' to fetch run JSONs (a user action), but the skill does not itself reach out to external endpoints.

Install Mechanism

No install spec — instruction-only with a shipped script — so nothing is downloaded or written by an installer. This is low-risk. (As noted, if you plan to use SKILL.md's gh example you must have the gh CLI installed separately; the installer does not provide it.)

Credentials

The skill requires only bash and python3 (declared). It lists no required environment variables or credentials. Be aware: the SKILL.md recommends using the GitHub CLI to export run JSONs; that step uses the user's gh authentication (outside this skill) but is not required by the script. The script does include sample run URLs and repo names in its output (these are derived from input JSONs and are not transmitted elsewhere by the script).

Persistence & Privilege

The skill does not request permanent presence (always:false), does not modify other skills or system-wide settings, and only reads inputs and writes to stdout/exit codes. It does not persist credentials or alter agent configuration.

Assessment

This script analyzes local GitHub Actions JSON exports — run it locally against a directory of exported run JSONs (default: artifacts/github-actions/*.json). The skill itself needs only bash and python3. SKILL.md shows how to collect runs with the GitHub CLI ('gh run view ...'), but 'gh' is not declared as a required binary and is not invoked by the script; if you use that collection step, 'gh' will use your GitHub auth (tokens) outside this skill. The script prints sample run URLs and repo names (it does not transmit them), so avoid running it in environments where printed output is automatically uploaded to an untrusted endpoint. If you plan to run this in CI, ensure RUN_GLOB matches only intended files and review outputs before storing or sharing. If you want the documentation to match runtime behavior, either install/declare 'gh' separately or remove the gh usage example from SKILL.md.

Use this skill to identify when failures cluster so teams can target flaky time windows and on-call coverage.

What this skill does

• Reads one or more GitHub Actions workflow run JSON exports
• Keeps only failure-like conclusions (failure, cancelled, timed_out, action_required, startup_failure)
• Buckets failures into day/hour windows (with optional timezone offset)
• Ranks windows by severity using failure-run thresholds
• Emits text or JSON output for dashboards or CI gates

Inputs

Optional:

• RUN_GLOB (default: artifacts/github-actions/*.json)
• TOP_N (default: 24)
• OUTPUT_FORMAT (text or json, default: text)
• WARN_FAILURE_RUNS (default: 3)
• CRITICAL_FAILURE_RUNS (default: 6)
• FAIL_ON_CRITICAL (0 or 1, default: 0)
• TZ_OFFSET_HOURS (default: 0) — integer timezone shift from UTC, between -23 and 23
• WORKFLOW_MATCH, WORKFLOW_EXCLUDE (regex, optional)
• BRANCH_MATCH, BRANCH_EXCLUDE (regex, optional)
• REPO_MATCH, REPO_EXCLUDE (regex, optional)

Collect run JSON

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

Run

Text report:

RUN_GLOB='artifacts/github-actions/*.json' \
WARN_FAILURE_RUNS=3 \
CRITICAL_FAILURE_RUNS=6 \
TZ_OFFSET_HOURS=7 \
bash skills/github-actions-failure-hour-audit/scripts/failure-hour-audit.sh

JSON output + fail gate:

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

Output contract

• Exit 0 in reporting mode
• Exit 1 when FAIL_ON_CRITICAL=1 and one or more critical windows are found
• Text output includes summary and top windows by severity
• JSON output includes summary, ranked windows, and critical_windows