agentleFS
sd0xdevsd0xdev/sd0x-harness/skills/watch-ci/SKILL.md

watch-ci

Skill192 starsChanged 42 days agoMITView on GitHub

Monitor GitHub Actions CI runs until completion. Use when: watching CI after push, checking build status, monitoring PR checks, waiting for CI completion, user says 'watch CI', 'check CI', 'CI status', 'monitor build', or /watch-ci. Not for: pushing code (use push-ci), creating PRs (use create-pr). Output: per-run verdict (pass/fail/timeout).

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If --run-id <id> is specified, skip run discovery and monitor that specific run directly.

    line 38
  2. Distinctive:

    If still no runs found after retries:

    line 55
  3. Distinctive:

    Before starting a long-running watch, check if runs are already completed:

    line 66
  4. Very specific:

    Wait for completion (blocking) — $INTERVAL only affects how often gh polls the API, not wall-clock completion

    line 104
  5. Very specific:

    If still running, launch gh run watch <run-id> --exit-status -i "$INTERVAL" with Bash(run_in_background: true).

    line 110

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Watch CI

Monitor GitHub Actions CI runs for the current HEAD (or a specified SHA) until completion, then report verdict.

Trigger

  • Keywords: watch CI, check CI, CI status, monitor build, build status, is CI passing, watch actions, CI result

When NOT to Use

  • Pushing code to remote (use /push-ci)
  • Creating pull requests (use /create-pr)
  • Running local tests (use /verify or /precommit)

Workflow

Auto-detect (branch + SHA) → Find matching runs → Quick-check status → Watch or Report → Verdict

Step 1: Resolve Target

Determine which CI runs to monitor. Use arguments if provided, otherwise auto-detect.

BRANCH=${ARG_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}
HEAD_SHA=${ARG_SHA:-$(git rev-parse HEAD)}
TIMEOUT=${ARG_TIMEOUT:-10}
INTERVAL=${ARG_INTERVAL:-30}

If --run-id <id> is specified, skip run discovery and monitor that specific run directly.

Step 2: Find CI Runs

Find runs matching the target SHA on the target branch:

gh run list --branch "$BRANCH" --limit 30 \
  --json databaseId,headSha,status,name,url

Note: Use --limit 30 (not 10) to avoid missing target SHA runs on busy branches. Filter results client-side by HEAD_SHA.

Filter results to those matching HEAD_SHA.

Retry logic: If no matching runs found, retry up to 3 times by re-running the gh run list command. The natural processing delay between retries provides sufficient wait time — do not use sleep N (N ≥ 2) as the first command, the harness will block it. All retry commands must start with gh or git to match allowed-tools. CI workflows may take a few seconds to trigger after push.

If still no runs found after retries:

⚠️ No CI run detected for SHA <sha>. Possible causes:
- No workflow configured for this branch
- Path-filtered workflow didn't trigger
- Check: gh run list --branch <branch>

Step 3a: Quick Status Check

Before starting a long-running watch, check if runs are already completed:

gh run view <run-id> --json status,conclusion,name,url
ResultAction
All runs completedSkip to Step 4 (Verdict) immediately — no watching needed
Some completed, some in progressReport completed verdicts, watch remaining (Step 3b)
All in progressProceed to Step 3b

Step 3b: Watch Runs

For each in-progress run, monitor with gh run watch:

gh run watch <run-id> --exit-status -i "$INTERVAL"

Poll interval: $INTERVAL defaults to 30 seconds (configurable via --interval). gh's own default is 3 seconds; at that rate, Monitor streaming surfaces ~20 notifications per minute, which has been reported as noisy. 30 seconds reduces poll noise by ~90% at the cost of ≤ 27 s additional completion-detection lag, which is negligible for typical multi-minute CI runs. Pass --interval 3 to restore the old cadence when near-real-time feedback matters.

Execution mode: Monitor streaming is the default — non-blocking, reliable notifications for each status line.

ModeWhenBehavior
Monitor (default)No mode flagStream gh run watch via Monitor tool. Each stdout line arrives as a notification. Claude processes verdict on completion. Non-blocking.
Foreground (--blocking)--blocking flag passedExecute gh run watch inline (blocking). Claude waits for completion, then reports verdict. Use when Monitor is unavailable or for simple single-run cases.
Background (--background)--background flag passedLaunch with Bash(run_in_background: true). Legacy fallback only — run_in_background delivers a single completion event, not streaming progress, so Monitor is preferred for rich updates. Provide a manual check command.

Monitor mode (default) — behavior:

  1. Launch gh run watch <run-id> --exit-status -i "$INTERVAL" via Monitor tool with description: "CI run <run-id> (<name>)" and timeout_ms: TIMEOUT * 60 * 1000
  2. Each stdout line (status update) arrives as a streaming notification — $INTERVAL controls how often those lines fire
  3. On exit (run completes or fails), parse final output for pass/fail status
  4. Report verdict

Foreground mode (--blocking) — behavior:

  1. Execute gh run watch <run-id> --exit-status -i "$INTERVAL" inline via Bash
  2. Wait for completion (blocking) — $INTERVAL only affects how often gh polls the API, not wall-clock completion
  3. Parse output for pass/fail status
  4. Report verdict

Background mode (--background) — legacy fallback only:

  1. Quick-check (Step 3a) first — if already completed, report immediately and skip background
  2. If still running, launch gh run watch <run-id> --exit-status -i "$INTERVAL" with Bash(run_in_background: true); $INTERVAL still applies (same gh call), but because background mode only surfaces a single completion event, poll cadence has no user-visible effect here
  3. Inform the user honestly: "CI monitoring launched in background for run <id>. Background notifications may not auto-report reliably. To check manually: gh run view <id> or re-run /watch-ci"
  4. Do NOT promise streaming progress updates — Bash(run_in_background: true) only delivers a single completion event, not per-status-line streaming; for rich updates, use Monitor mode

Multiple runs: If multiple workflow runs match (e.g. CI + Auto Release), launch parallel Monitor instances — one per run. Each Monitor reports its own per-run verdict via notifications. Overall verdict = worst individual result (any fail → overall fail). In --blocking mode, watch sequentially. In --background mode, launch each as a separate background task.

Timeout enforcement: Default 10 minutes (configurable via --timeout). In Monitor mode, set timeout_ms: TIMEOUT * 60 * 1000 (Monitor tool enforces deadline). In --blocking mode, enforce via Bash tool's timeout parameter (milliseconds). If a timeout occurs, report the run as timed out. Timeout applies per individual run invocation, not to the entire monitoring session.

Step 4: Verdict

CI ResultOutput
All pass"✅ CI passed" + per-run URLs
Any failFailing jobs + gh run view <id> --log-failed summary
Timeout"⚠️ CI still running after <N>min — gh run watch <id>"

Overall verdict = worst individual result (any fail → overall fail).

Prohibited Actions

❌ Running `gh run view` once and treating that as "monitoring" — one-shot status check is NOT watching
❌ Promising per-status-line streaming updates in background mode — `Bash(run_in_background: true)` only delivers a single completion event; use Monitor for rich streaming
❌ Skipping the quick-check step (Step 3a) — always check status before deciding to watch
❌ Reporting "CI monitoring started" without actually launching `gh run watch`
❌ Using `gh run list` results as the final verdict — list shows status at query time, not completion
❌ Using `sleep N` (N ≥ 2) as the first Bash command — harness blocks it; retry by re-running `gh run list` directly
❌ Using commands outside `allowed-tools` (only `gh`, `git`, `Read`, and `Monitor` are permitted)
❌ Using `Bash(run_in_background: true)` when Monitor is available — Monitor is the preferred streaming mechanism

Arguments

ArgumentDescriptionDefault
--sha <sha>SHA to monitorgit rev-parse HEAD
--branch <branch>Branch to filter runsgit rev-parse --abbrev-ref HEAD
--timeout <min>Watch timeout in minutes10
--interval <sec>Poll interval for gh run watch -i — controls how often gh queries the API and emits a status line (Monitor mode surfaces each line as one notification)30
--run-id <id>Monitor a specific run ID directlyauto-detect
--blockingUse foreground blocking mode instead of Monitor streamingMonitor
--backgroundLegacy fallback: launch in background (unreliable auto-reporting)Monitor

Output

## CI Monitor Report

**Branch**: `<branch>`
**SHA**: `<sha>`

| Run | Name | Status | URL |
|-----|------|--------|-----|
| 123 | CI | ✅ Pass | https://github.com/.../runs/123 |
| 124 | Auto Release | ✅ Pass | https://github.com/.../runs/124 |

## Verdict: ✅ All Pass / ⛔ N failures

Verification

  • Target SHA resolved (from argument or auto-detect)
  • CI runs matched by SHA (not "latest")
  • All matching runs monitored
  • Verdict reported (pass/fail/timeout)

Examples

Input: /watch-ci
Action: Auto-detect HEAD SHA → find matching runs → quick-check status
  If completed → report verdict immediately
  If still running → launch Monitor stream per run → receive status notifications → report verdict on completion

Input: /watch-ci --sha abc1234
Action: Find runs for SHA → quick-check → Monitor stream if needed → verdict

Input: /watch-ci --run-id 12345678
Action: Quick-check run 12345678 → Monitor stream if still running → verdict

Input: /watch-ci --blocking
Action: Auto-detect → find runs → quick-check
  If completed → report immediately
  If still running → foreground watch (blocking) → wait → report verdict

Input: /watch-ci --background
Action: Auto-detect → find runs → quick-check
  If completed → report immediately (no background needed)
  If still running → launch background watch (legacy) → "CI monitoring launched, check manually with `gh run view <id>`"

Input: Is CI passing?
Action: Auto-detect → find runs → quick-check → Monitor stream if needed → verdict

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.