github-actions-monitor

name	github:actions-monitor
description	Monitor GitHub Actions runs and extract failure diagnostics. Use when watching PR CI, branch builds, or specific workflow runs.
argument-hint	[pr-url | branch | run-id] [--max-minutes N] [--interval S]
effort	low
allowed-tools	["Monitor","TaskStop","Agent","Bash(bun:*)","Bash(gh run:*)","Bash(gh pr view:*)","Bash(gh pr checks:*)","Bash(git remote:*)","Bash(jq:*)"]

Actions Monitor

Watch a PR, branch, or specific run's GitHub Actions progress and react to failures by pulling logs through the github:logs agent. The watch script handles state tracking and deduplication. This skill starts it, reacts to events, and stops it.

Target

$ARGUMENTS

• A GitHub PR URL runs in PR mode. Owner and repo come from the URL, so PR mode works from any working directory.
• A branch name runs in branch mode.
• A run ID runs in run-id mode, watching a specific workflow run directly (covers workflow_dispatch, manual triggers, and re-runs).
• No argument: derive the current PR with gh pr view --json url --jq '.url'. If the branch has no PR, fall back to branch mode with the current branch name.

Branch and run-id mode infer the repo from git remote get-url origin; pass --repo <owner/repo> to override.

Workflow

Start the monitor

Invoke Monitor with persistent: true on the watch script, with exactly one mode flag:

bun ${CLAUDE_SKILL_DIR}/scripts/watch.ts --pr <pr-url>
bun ${CLAUDE_SKILL_DIR}/scripts/watch.ts --branch <name> [--repo <owner/repo>]
bun ${CLAUDE_SKILL_DIR}/scripts/watch.ts --run-id <id> [--repo <owner/repo>]

Optional flags: --interval <seconds>, --max-minutes <N>, --queued-timeout <minutes>, --api-error-threshold <N>. Omit --interval to let the script derive one from recent run durations in PR/branch mode; run-id mode uses a 180s default.

Event schema

The script emits one JSON object per line on stdout:

• {"type":"status","state":"running|failing|success","sha":"...","run_id":"..."}
• {"type":"conflicts","sha":"..."} (PR mode only)
• {"type":"mergeable-unknown","sha":"..."} (PR mode only)
• {"type":"queued-timeout","minutes":N}
• {"type":"api-error","consecutive":N}
• {"type":"rate-limited","retry_after":"..."}
• {"type":"pr-closed"} (PR mode only; also fires if the branch is deleted)
• {"type":"merged"} (PR mode only)
• {"type":"max-time-reached","minutes":60}

If the target is already green at startup, the script emits a single status:success and exits.

The script exits on status:success, pr-closed, merged, and max-time-reached. In run-id mode it also exits on status:failing, since a specific run reaches a terminal conclusion with no "next run" to wait for. In PR and branch mode, failing is not terminal (the user may push a fix or start another run). To stop early, call TaskStop on the monitor task.

React to events

On a status event with state == "failing", invoke the github:logs agent via the Agent tool, passing the run_id and the PR URL (or branch name) from the event. It returns a structured JSON summary of the failing jobs and persists the raw logs to a known temp path; read that file for more context.

• conflicts / mergeable-unknown (PR mode): note the SHA; the caller (e.g. pull-request:babysit) decides whether to resolve or run an authoritative local check. mergeable-unknown means GitHub could not settle mergeability after bounded re-polling.
• queued-timeout / api-error: surface to the user.
• rate-limited: back off and retry once the window passes.

References

Log parsing strategy (shared with github:logs): references/log-parsing.md.