CI Orchestration

Comprehensive CI/CD workflow management with fail-fast error detection and preview URL extraction.

Purpose

CI Orchestration provides explicit control over GitHub Actions and other CI systems. Monitor check status, extract preview URLs, debug failures, and manage workflow retries with intelligent fail-fast patterns.

When to Use

• Waiting for CI checks with real-time status
• Extracting preview deployment URLs (Vercel, Netlify)
• Debugging CI failures
• Retrying failed workflows
• Managing CI in complex workflows

Core Capabilities

Check CI Status

# Check PR status
gh pr checks 42

# Watch and wait
gh pr checks 42 --watch

# Get JSON output
gh pr view 42 --json statusCheckRollup

Extract Preview URLs

The existing ci-status.ts utility provides comprehensive preview URL extraction:

import { extractPreviewUrls } from '../shared/hooks/utils/ci-status.js';

// Extract from CI output
const urls = extractPreviewUrls(ciOutput);
// Returns: { web: 'https://...', marketing: 'https://...' }

Fail-Fast Patterns

# Wait with fail-fast
awaitCIWithFailFast "$PWD" 42 10  # 10 minute timeout

# Detects:
# - Merge conflicts
# - Branch divergence
# - Failed checks
# - Workflow errors

Retry Failed Checks

# Get latest workflow run
RUN_ID=$(gh run list --branch $(git branch --show-current) --limit 1 --json databaseId -q '.[0].databaseId')

# Re-run failed jobs
gh run rerun $RUN_ID --failed

Integration with Hooks

Hook	Behavior
await-pr-status	Waits for CI after gh pr create
commit-task-await-ci-status	Auto-commits and checks CI on SubagentStop
commit-session-await-ci-status	Blocking CI check on Stop

Utilities

From ci-status.ts:

• awaitCIWithFailFast(cwd, prNumber, timeout) - Wait with fail-fast
• extractPreviewUrls(output) - Parse Vercel/Netlify URLs
• getLatestCIRun(cwd, branch) - Get workflow run ID
• formatCiChecksTable(checks) - Format as markdown table

Examples

Wait for CI with Preview URLs

# Create PR
PR=$(gh pr create --title "Add feature" --body "..." --json number -q .number)

# Wait for CI
awaitCIWithFailFast "$PWD" $PR 10

# Extract preview URLs
CHECKS=$(gh pr view $PR --json statusCheckRollup -q '.statusCheckRollup')
PREVIEW=$(extractPreviewUrls "$CHECKS")

echo "Preview: $PREVIEW"

Debug Failed CI

# Get failed checks
gh pr checks 42 --json name,conclusion,detailsUrl \
  --jq '.[] | select(.conclusion=="FAILURE") | {name, url: .detailsUrl}'

# View logs
gh run view $(gh run list --limit 1 --json databaseId -q '.[0].databaseId') --log-failed

Retry with Backoff

MAX_RETRIES=3
RETRY=0

while [ $RETRY -lt $MAX_RETRIES ]; do
  if gh pr checks $PR --watch; then
    echo "✓ CI passed"
    break
  fi

  RETRY=$((RETRY + 1))
  if [ $RETRY -lt $MAX_RETRIES ]; then
    echo "Retry $RETRY/$MAX_RETRIES..."
    gh run rerun $(gh run list --limit 1 --json databaseId -q '.[0].databaseId') --failed
  fi
done

Best Practices

1. Use fail-fast patterns (10min timeout)
2. Extract and share preview URLs
3. Auto-retry transient failures (max 3 times)
4. Parse logs for actionable errors
5. Update PR comments with CI status