monitor-ci

Babysit a CI Run

Waiting on a pipeline looks like a one-line job and is not. Three things go wrong, and each one produces a confident but wrong report: the wrong run gets watched, the waiting strategy exhausts the session before the run finishes, or the run's outcome is read off a summary that hides a suppressed failure.

This skill is the mechanics of getting from "it is running" to "here is what actually happened". Whether the green that comes out is evidence is a separate question, and it belongs to prove-checks.

Trigger

• A run must reach a conclusion before the next step can start.
• The task says wait for, watch, babysit, or monitor a build, release, deploy or pipeline.
• A failed run must be restarted, possibly more than once.
• Another party is blocked on the answer "did it go green?"

Procedure

1. Confirm the run is the one you were asked about

A run URL or id identifies a run, not an intent. Before waiting on it, read back what it actually is and check it against the request:

gh api repos/<owner>/<repo>/actions/runs/<run-id> \
  --jq '{name, event, status, conclusion, head_branch, head_sha, attempt: .run_attempt}'

Watch for a run that is a previous attempt, that is on an unexpected branch, or whose event is not what the task described. When the run was dispatched with inputs that matter — a version, an environment, a dry-run flag — those inputs are not in this payload. They appear in the dispatching step's logs, which are unavailable until the run completes (see step 3), so verify them against the artifact the run produces rather than assuming.

2. Wait in bounded blocks, not one open-ended call

A blocking watcher is the obvious tool and the one that fails: gh run watch does not return until the run ends, so on a long run it outlives whatever timeout wraps it and the wrapper kills it with nothing to show. Budget explicitly instead.

• Wrap any blocking watch in a timeout comfortably shorter than the tool call's own limit, and treat a timeout as "not finished yet" rather than an error: timeout 580 gh run watch <run-id> --exit-status.
• Re-issue it, or fall back to polling --jq .status on an interval, until status reads completed.
• Keep a detached poller writing to a log file when the wait may span several turns. It costs nothing and survives the foreground call being cut short.