CI Checker

Checks GitHub CI status for PRs and guides fixing any failures.

Configuration

# Required environment variables
PIPELINE_API_URL=http://localhost:3000  # Pipeline API endpoint
AGENT_ID=ci-checker                      # Agent identifier

Prerequisites

• PR must exist
• Must be in a git repository with GitHub remote
• gh CLI authenticated
• Pipeline API running and accessible

Workflow

1. Get Ticket and PR Info

import { PipelineClient, PipelineAPIError } from '@pipeline/client'

const client = new PipelineClient({
  apiUrl: process.env.PIPELINE_API_URL!,
  agentId: process.env.AGENT_ID!,
})

const ticket = await client.getTicket(ticketId)
const prNumber = ticket.prNumber
const prUrl = ticket.prUrl

If no PR number on ticket, ask: "PR number? (or paste URL)"

2. Check CI Status

gh pr checks {pr-number}

Parse each check for status:

• ✅ pass
• ❌ fail
• 🔄 pending

3. Report Status

Present as table:

# CI Status for PR #{number}

| Check     | Status     | Duration |
| --------- | ---------- | -------- |
| lint      | ✅ pass    | 2m       |
| typecheck | ✅ pass    | 3m       |
| test-unit | ❌ fail    | 5m       |
| test-e2e  | 🔄 pending | -        |
| build     | ✅ pass    | 4m       |

## Overall: {Passing / Failing / Pending}

4. Handle Pending

If checks still running:

CI checks still running. Estimated time: {X} minutes.

Options:
A) Wait and check again in 5 minutes
B) Check specific workflow status
C) Continue anyway (not recommended)

5. Handle Failures

For each failing check, get details:

# Get JSON with run IDs
gh pr checks {pr-number} --json name,status,conclusion,detailsUrl

# Get logs for failing run
gh run view {run-id} --log-failed

Present failure summary:

## Failed: {check-name}

### Error Summary

{extracted error message}

### Failed Tests

- `src/components/Foo.test.ts` - "expected true, got false"

### Suggested Fix

{analysis based on error type}

6. Guide Fixes

Found {X} failing checks.

Options:
A) Investigate and fix locally
B) Re-run failed checks (if flaky)
C) View full logs for {check}
D) Ignore and proceed (not recommended)

Choice:

Option A - Fix locally:

• Provide commands to reproduce locally
• Dispatch subagent to investigate
• After fix, commit and push
• Re-check CI

Option B - Re-run:

gh run rerun {run-id} --failed

Wait and check again.

Option C - View logs:

gh run view {run-id} --log

Present relevant sections.

7. Handle All Passing

✅ All CI checks passing!

PR is ready for review.

Options:
A) Transition ticket to Done via API
B) Request specific reviewers
C) Done for now

If transitioning to Done (Option A):

await client.transitionState(ticketId, 'DONE', 'ci-passed-and-merged')

8. Update State via API

After CI passes and PR is merged, transition state:

await client.transitionState(ticketId, 'DONE', 'ci-passed-and-merged')

Common Issues & Solutions

E2E Test Flakes

• Cause: Timing issues, async operations
• Solution: Re-run with gh run rerun --failed
• If persists: Fix the flaky test

Lint Differences

• Cause: Different eslint/prettier versions
• Solution: Run pnpm install and pnpm lint:fix locally

Type Errors in CI Only

• Cause: Stricter tsconfig or different TS version
• Solution: Run exact same typecheck command as CI

Build Failures

• Cause: Missing files, import errors
• Solution: Run pnpm build locally to reproduce

Key Commands

# List all checks
gh pr checks {pr-number}

# Get check details as JSON
gh pr checks {pr-number} --json name,status,conclusion,detailsUrl

# View run details
gh run view {run-id}

# View failed logs only
gh run view {run-id} --log-failed

# View full logs
gh run view {run-id} --log

# Re-run failed jobs
gh run rerun {run-id} --failed

# Re-run entire workflow
gh run rerun {run-id}

Notes

• E2E tests can take 10-20 minutes - don't poll too frequently
• One re-run for flaky tests is acceptable
• If same test fails twice, it's a real issue
• Some checks are required for merge, some optional
• Never force merge with failing required checks
• CI status is checked via gh CLI—the API is used for ticket metadata and state transitions