wait-for-ci

Wait for CI

Wait for CI/CD pipelines to finish and get actionable results — without burning context on polling logic. Everything deterministic is handled by scripts. Your job is to spawn them and act on what comes back.

Why Scripts Handle the Waiting

Polling a CI system is pure mechanics — no reasoning needed. The wait-ci.sh script handles all the waiting, retrying, and status parsing. Running it as a background task means you can do other work while CI runs, and you get notified with structured JSON when it finishes.

Quick Start

Two steps: detect, then wait.

Step 1: Detect CI System

bash <skill-path>/scripts/detect-ci.sh /path/to/project

Returns JSON like:

{
  "ci": "github-actions",
  "deploy": "vercel",
  "config_file": ".github/workflows/ci.yml",
  "workflow_count": 3,
  "repo": "owner/repo",
  "branch": "feature-x",
  "sha": "abc1234",
  "tools": { "gh": true, "glab": false, "vercel": true }
}

If ci is "unknown", tell the user no CI configuration was found and ask what they use.

If the required CLI tool is missing (tools.gh, tools.glab, or tools.vercel is false), tell the user to install it before proceeding.

Step 2: Wait as a Background Task

Run the wait script with run_in_background: true so you stay unblocked:

bash <skill-path>/scripts/wait-ci.sh github-actions \
  --repo owner/repo \
  --branch feature-x \
  --sha abc1234 \
  --timeout 600

The script blocks until CI finishes (or times out), then outputs JSON:

{
  "ci": "github-actions",
  "repo": "owner/repo",
  "branch": "feature-x",
  "sha": "abc1234",
  "status": "completed",
  "conclusion": "failure",
  "elapsed_seconds": 142,
  "details": "Failed: lint: failure; | Logs: error: unused variable...",
  "url": "https://github.com/owner/repo/actions/runs/12345"
}

Step 3: Act on Results

When the background task completes, you get the JSON. Use it:

conclusion	What to do
success	Report success. Proceed with next steps (merge, deploy, etc.)
failure	Read the details field for failed jobs and log excerpts. Fix the issue and push again.
cancelled	Tell the user CI was cancelled — they may need to re-trigger.
timeout	CI took too long. Link the user to the run URL so they can check manually.
missing_tool	Tell the user which CLI tool to install.
no_run_found	Push may not have triggered CI. Check if workflows exist for this branch.

When CI fails, the details field contains the failed job names and a log excerpt (last 30 lines of the failed step). This is usually enough to identify the issue without manually opening the CI dashboard.

Monitoring Both CI and Deployment

Some projects have both CI (GitHub Actions) and deployment (Vercel). You can run both in parallel as separate background tasks:

# Background task 1: CI
bash <skill-path>/scripts/wait-ci.sh github-actions --repo owner/repo --branch main

# Background task 2: Deployment
bash <skill-path>/scripts/wait-ci.sh vercel --branch main

Each will notify you independently when done.

Typical Agent Workflows

Push-and-Verify

After pushing a fix or feature:

1. Run detect-ci.sh to get the CI config
2. Spawn wait-ci.sh as a background task
3. Continue working on other tasks (or tell the user you're waiting)
4. When notified, report the result or fix failures

Iterative Fix Loop

When CI fails:

1. Read the failure details from the JSON output
2. Fix the issue in code
3. Commit and push
4. Spawn a new wait-ci.sh background task for the new commit
5. Repeat until green

Pre-Merge Gate

Before merging a PR:

1. Spawn wait-ci.sh for the PR branch
2. Only proceed with merge when conclusion is success
3. If it fails, fix and re-push instead of merging broken code

Supported CI Systems

System	CLI Required	Detection	Wait Method
GitHub Actions	gh	.github/workflows/*.yml	gh run watch (blocking, efficient)
GitLab CI	glab	.gitlab-ci.yml	glab ci status (polling)
Vercel	vercel	vercel.json or .vercel/	vercel inspect (polling)

GitHub Actions uses gh run watch which is a native blocking wait — no polling overhead. GitLab and Vercel use periodic polling at 15-second intervals.

Options

Flag	Default	Description
--repo	From git remote	Repository in owner/repo format
--branch	Current branch	Branch to monitor
--sha	Current HEAD	Commit SHA to match
--timeout	600 (10 min)	Max seconds to wait before timing out
--poll	15	Seconds between status checks (GitLab/Vercel only)