tomevault-io 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-fastextractPreviewUrls(output)- Parse Vercel/Netlify URLsgetLatestCIRun(cwd, branch)- Get workflow run IDformatCiChecksTable(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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.