GitHub Actions Stuck Run Audit

Detect stale queued/in-progress GitHub Actions runs before they quietly block delivery.

Security Scan

The skill is mostly coherent for auditing local GitHub Actions run JSON files, but there are small mismatches (notably the SKILL.md uses the 'gh' CLI while the skill's declared required binaries omit it) and the script will process arbitrary file globs which could be pointed at sensitive files if misused.

Purpose & Capability

The name/description match the included script: it reads exported GitHub Actions run JSON files and computes stuck/run risk. However, SKILL.md demonstrates collecting data using the 'gh' CLI (gh run view) but the declared required binaries list only 'bash' and 'python3' — 'gh' is not declared. That mismatch is likely an omission in metadata (documentation vs declared requirements) but is an incoherence the user should be aware of.

Instruction Scope

The runtime instructions and included script operate on local JSON files matched by RUN_GLOB and do not perform network calls or attempt to read unrelated system state. The script's behavior (filters, grouping, thresholds, exit codes) is explicit. One scope note: RUN_GLOB is user-configurable, so the skill will read any files the runner points it at; the default is a dedicated artifacts path.

Install Mechanism

This is an instruction-only skill with a bundled script; there is no install step, no external downloads, and nothing is written to disk beyond running the provided script. Risk from installation is low.

Credentials

The skill declares no required environment variables or credentials (proportionate for a local JSON analyzer). But it relies on environment variables for configuration (RUN_GLOB, filters, thresholds). Because RUN_GLOB can be set to arbitrary paths, a user/agent could instruct the skill to read sensitive files — this is not malicious in the script itself but is a capability the user should intentionally control. Also, SKILL.md suggests using 'gh' to create the JSON exports, yet 'gh' is not included in required env/bins.

Persistence & Privilege

The skill does not request persistent installation or elevated platform privileges; always:false and normal autonomous invocation. It does not attempt to modify other skills or system-wide agent settings.

What to consider before installing

This skill appears to do what it says (analyze local GitHub Actions run JSONs), but check these before installing: 1) SKILL.md shows use of the 'gh' CLI to produce JSON files, yet 'gh' is not listed in required binaries — ensure you have 'gh' available or export the run JSONs by another trusted method. 2) The script reads any files matched by RUN_GLOB — keep RUN_GLOB constrained to trusted artifact directories so the tool can't be pointed at secrets or unrelated system files. 3) Review the included script if you plan to run it in CI: it embeds a Python program and will exit non‑zero in some error cases (and can fail CI gates when FAIL_ON_CRITICAL=1). 4) Run the tool on known fixtures first (SKILL.md shows a fixtures invocation) or in a sandboxed environment to confirm behavior. If you need higher assurance, ask the author to update metadata to declare 'gh' as a required binary and to document any expected file formats and safe default RUN_GLOB locations.

Use this skill to catch workflows that are stuck in queued/in-progress states for too long.

What this skill does

• Reads GitHub Actions run JSON exports
• Detects stale runs in non-terminal statuses (queued, in_progress, etc.)
• Aggregates stuck risk by repo/workflow (or repo/branch)
• Scores severity with stuck-age, stuck-run volume, and stuck-rate thresholds
• Emits ok / warn / critical and can fail CI gates

Inputs

Optional:

• RUN_GLOB (default: artifacts/github-actions/*.json)
• TOP_N (default: 20)
• OUTPUT_FORMAT (text or json, default: text)
• GROUP_BY (repo, repo-workflow, repo-workflow-branch; default: repo-workflow)
• NOW_ISO (optional ISO timestamp override for deterministic replay)
• STUCK_STATUSES (comma list, default: queued,in_progress,pending,waiting,requested)
• WARN_STUCK_MINUTES (default: 45)
• CRITICAL_STUCK_MINUTES (default: 120)
• WARN_STUCK_RUNS (default: 2)
• CRITICAL_STUCK_RUNS (default: 4)
• WARN_STUCK_RATE (0..1, default: 0.2)
• CRITICAL_STUCK_RATE (0..1, default: 0.45)
• MIN_RUNS (default: 1)
• WORKFLOW_MATCH / WORKFLOW_EXCLUDE (regex, optional)
• BRANCH_MATCH / BRANCH_EXCLUDE (regex, optional)
• EVENT_MATCH / EVENT_EXCLUDE (regex, optional)
• REPO_MATCH / REPO_EXCLUDE (regex, optional)
• STATUS_MATCH / STATUS_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-stuck-run-audit/scripts/stuck-run-audit.sh

JSON output + fail gate:

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

Run against bundled fixtures:

NOW_ISO='2026-03-08T00:00:00Z' \
RUN_GLOB='skills/github-actions-stuck-run-audit/fixtures/*.json' \
bash skills/github-actions-stuck-run-audit/scripts/stuck-run-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 stuck-risk groups
• JSON mode prints summary + ranked groups + critical groups