Agent-Skills.md

Agent Skills: CI Monitor

Monitor and watch GitHub Actions CI/CD pipeline runs in real time. Use when the user has pushed code and wants to watch the build, check CI status, see if tests passed, monitor a pipeline, or wait for a workflow run to complete. Also use after any `jj git push` or `git push` command. Reports pass/fail with failed job logs. Do NOT use for writing or editing CI workflow YAML files, optimizing CI config, or debugging CI configuration — only for monitoring active runs.

UncategorizedID: trevors/dot-claude/monitoring-ci

Repository

trevors/dot-claude
TrevorS
5

Install this agent skill to your local

pnpm dlx add-skill https://github.com/TrevorS/dot-claude/tree/HEAD/skills/monitoring-ci

Skill Files

Browse the full folder contents for monitoring-ci.

Download Skill

Loading file tree…

skills/monitoring-ci/SKILL.md

Skill Metadata

Name
monitoring-ci
Description
Monitor and watch GitHub Actions CI/CD pipeline runs in real time. Use when the user has pushed code and wants to watch the build, check CI status, see if tests passed, monitor a pipeline, or wait for a workflow run to complete. Also use after any `jj git push` or `git push` command. Reports pass/fail with failed job logs. Do NOT use for writing or editing CI workflow YAML files, optimizing CI config, or debugging CI configuration — only for monitoring active runs.

CI Monitor

Watch GitHub Actions CI runs after a push. Auto-detects repo and branch, deduplicates concurrent monitors, reports results.

Interpreting skill arguments

Anything on the ARGUMENTS: line is a set of monitoring parameters, never a task description. Pick out the branch name and/or hex commit SHA and pass them as --branch / --sha; ignore filler words like "push", "commit", or "monitor". For example, ARGUMENTS: master push 0bed725ba7cb means:

uv run ~/.claude/skills/monitoring-ci/ci-monitor.py --branch master --sha 0bed725ba7cb

This skill is strictly read-only: run ci-monitor.py and report its result. Do NOT edit ci-monitor.py, this file, or any other file; do NOT commit, push, or change the script's interface — even if the arguments look like they don't match the script's flags. If you can't extract a branch or SHA from the arguments, run the script with no flags (it auto-detects) and say so in your report.

Usage

Run the script in the background after pushing:

uv run ~/.claude/skills/monitoring-ci/ci-monitor.py

With explicit branch:

uv run ~/.claude/skills/monitoring-ci/ci-monitor.py --branch my-feature

How to Invoke from Claude

After a push, resolve the HEAD SHA before launching the background command, then pass it via --sha:

# Get the SHA that was just pushed (jj or git)
SHA=$(jj log -r '@-' --no-graph -T 'commit_id' 2>/dev/null || git rev-parse HEAD)

# Run in background with SHA pinning
uv run ~/.claude/skills/monitoring-ci/ci-monitor.py --branch <branch-name> --sha "$SHA"

Use run_in_background: true so it doesn't block the conversation. Tell the user: "CI monitor running in background — you'll be notified when it completes."

IMPORTANT: Always pass --sha to avoid watching a stale run from a previous push. The monitor matches runs by SHA, so it will wait for the correct run to appear.

Features

  • Auto-detects branch: jj bookmarks first, falls back to git
  • Deduplicates per push: sentinel at /tmp/{repo}-ci-monitor-{sha12} prevents double-watching the same push, while monitors for different pushes coexist; stale sentinels (dead monitor) are taken over automatically
  • Polls for run: waits up to 180s for a CI run to appear on the branch (configurable via --timeout); sleeps 5s first so GitHub has time to register the run
  • Watches until done: polls gh run view --json status,conclusion every 10s — a transient API error delays detection by one poll instead of crashing the watcher (which is what gh run watch does on a TCP reset)
  • Reports failure logs: on failure, fetches gh run view --log-failed (last 3000 chars)
  • Cleans up: always removes sentinel, even on error

Exit Codes

  • 0 — CI passed (or another monitor already active for this push)
  • 1 — CI failed (logs printed)
  • 2 — indeterminate: no run found, watch timed out, or gh API kept erroring. NOT a pass — report the manual-check command from the output.

Requirements

  • gh CLI authenticated
  • GitHub Actions workflows in the repo