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
-
Use fail-fast patterns (10min timeout)
-
Extract and share preview URLs
-
Auto-retry transient failures (max 3 times)
-
Parse logs for actionable errors
-
Update PR comments with CI status