You can enable AI agents to monitor GitHub pull request (PR) status by polling CI checks. This approach ensures an automated process of delivering quality code by AI agent.
It can be used in any AI Agentic workflow. For example, Claude Code, Cursor, etc.
Add the script and instructions, and enjoy the magic.
# scripts/poll_ci.sh
#!/usr/bin/env bash
set -euo pipefail
PR="$1"
INTERVAL="${2:-15}" # seconds
TIMEOUT="${3:-600}" # seconds
START=$(date +%s)
# Auto-detect repository owner and name if not provided
if [[ -z "${OWNER:-}" ]] || [[ -z "${REPO:-}" ]]; then
REPO_INFO=$(gh repo view --json owner,name -q '.owner.login + "/" + .name')
OWNER=$(echo "$REPO_INFO" | cut -d'/' -f1)
REPO=$(echo "$REPO_INFO" | cut -d'/' -f2)
fi
echo "↪️ Polling PR #$PR every $INTERVAL s for $TIMEOUT s max"
while :; do
# We use `|| true` so that `gh`'s non-zero exit code on pending or
# failed checks don't trigger `set -e` and kill the script.
CHECKS_OUTPUT=$(gh pr checks "$PR" --repo "$OWNER/$REPO" 2>&1 || true)
if echo "$CHECKS_OUTPUT" | grep -E "fail|failure|error" -q; then
echo "❌ PR #$PR is red"
echo "$CHECKS_OUTPUT"
exit 1
elif echo "$CHECKS_OUTPUT" | grep "pending" -q; then
echo "• $(date +"%H:%M:%S") → pending"
elif ! echo "$CHECKS_OUTPUT" | grep -E "fail|failure|error|pending|skipping" -q; then
# If there are no failing, pending, or skipping checks, we can assume success.
# This is more robust than just checking for "pass", as some CIs might
# not report a passing state explicitly if all jobs are neutral/successful.
echo "✅ PR #$PR is green"
echo "$CHECKS_OUTPUT"
exit 0
else
# This state means there are no failures and no pending, but some are
# skipping or in another state. We wait.
echo "• $(date +"%H:%M:%S") → waiting for checks to complete"
fi
(( $(date +%s) - START > TIMEOUT )) && {
echo "⏰ PR #$PR timed out"
echo "$CHECKS_OUTPUT"
exit 2
}
sleep "$INTERVAL"
done
AI Instructions
Note: Can be added to CLAUDE.md or Cursor rules
# Poll CI Status: $ARGUMENTS
Use this command when you need to wait for all GitHub checks on a pull-request to complete and then branch into success or failure flows.
## Parameters (space-separated)
| Pos | Name | Example | Purpose |
| --- | ---------- | ------- | ------------------------------------------------------- |
| 1 | `pr_id` | `123` | Pull-request number to monitor |
| 2 | `interval` | `15` | *(optional, default 15 s)* seconds between status polls |
| 3 | `timeout` | `600` | *(optional, default 600 s)* maximum wait in seconds |
## Environment Variables (optional)
| Name | Example | Purpose |
| ------- | -------------------- | ------------------------------------------------------------ |
| `OWNER` | `RAILS` | Repository owner (auto-detected from current repo if unset) |
| `REPO` | `RAILS` | Repository name (auto-detected from current repo if unset) |
**Run polling script**
`./scripts/poll_ci.sh $ARGUMENTS`
The script will automatically detect the repository owner and name from the current directory if not provided via environment variables.