Gh Fix CI

GitHub PR Checks Fix

Use This Skill When

• GitHub Actions checks failing on your PR
• Need to understand why CI/CD workflow failed
• Want actionable fix plan for failing tests/builds
• Debugging workflow configuration issues
• Fixing flaky tests or environment problems
• Non-GitHub Actions checks: report details URL only (out of scope)

When NOT to Use

• External CI systems (Buildkite, CircleCI, Travis)
• Complex approval workflows requiring multiple stakeholders
• Workflow failures in protected branches (needs admin)
• Local debugging (local testing more efficient)

Context: CI Debugging Maturity

Undeveloped: Click through GitHub UI, read raw logs, guess at fixes.

Target: Fetch logs via CLI, summarize failure, draft plan, implement after approval.

Optimized: Predict root causes, suggest preventive measures, auto-retry flaky tests, integrated remediation.

Core Principle

Failed CI should be actionable. Fetch logs programmatically, surface the actual failure context (not noise), create a concrete plan, and let the developer decide how to fix.

Instructions

Step 1: Verify gh CLI Authentication

Check auth status:

gh auth status

If not authenticated:

gh auth login
# Select GitHub.com, HTTPS or SSH
# Authorize with scopes: repo, workflow

Verify elevated permissions:

gh auth refresh --scopes repo,workflow

Step 2: Resolve the PR

Find current branch's PR:

gh pr view --json number,url,title

Or specify PR explicitly:

gh pr view 123  # PR number
# or
gh pr view https://github.com/owner/repo/pull/123  # Full URL

Step 3: Inspect Failing Checks

List all checks on PR:

gh pr checks [PR] --json name,state,conclusion,url,detailsUrl

Filter for failures:

gh pr checks [PR] --json name,state,conclusion,url,detailsUrl | \
  jq '.[] | select(.conclusion == "FAILURE" or .state == "FAILURE")'

Step 4: Fetch Detailed Failure Logs

For GitHub Actions failures:

# Get run details
gh run view [RUN_ID] --json name,workflowName,conclusion,status,url,event,headBranch

# Fetch full logs
gh run view [RUN_ID] --log > failure_logs.txt

# Or fetch specific job logs
gh api "/repos/OWNER/REPO/actions/jobs/JOB_ID/logs" > job_logs.txt

For non-GitHub Actions (external):

❌ External CI detected: [System Name]
📋 Details URL: [Link]
⏭️ Out of scope for this skill
👉 Visit the link above to debug manually

Step 5: Summarize Failure Context

Extract key failure snippet:

## Failed Check Summary

**Check Name**: tests-ubuntu
**Status**: ❌ FAILURE
**Run ID**: [RUN_ID]
**URL**: [GitHub Actions Run URL]

### Error Context

**Last 30 lines of output:**

[STDERR snippet from logs showing actual failure]

**Likely Root Cause**: 
- Test assertion failed: `expect(result).toBe(true)`
- Expected: true
- Received: false

**Context**:
- Test file: `src/utils.test.ts`
- Test name: "parseConfig returns valid structure"
- Failure appears consistent (not flaky)

**Next Steps**: Needs investigation of config parsing logic

Step 6: Create Fix Plan

Use plan skill to draft:

# Plan: Fix Test Failure in tests-ubuntu

We need to debug why `parseConfig()` is returning false instead of true.

## Scope

**In:**
- Review parseConfig logic in src/utils.ts
- Check test expectations in src/utils.test.ts
- Verify mock data/fixtures

**Out:**
- Refactoring entire config system
- Upgrading testing framework

## Action Items

- [ ] Run test locally: `npm test -- src/utils.test.ts`
- [ ] Add console.log to see actual parseConfig output
- [ ] Compare expected vs. actual config structure
- [ ] Fix parseConfig or update test expectations
- [ ] Verify test passes locally
- [ ] Push changes and verify CI passes

## Open Questions

- Is the test expectation correct?
- Did a recent code change break parseConfig?

Step 7: Implement After User Approval

After user approves plan:

1. Make code changes

   # Edit files based on plan
   code src/utils.ts  # Fix the logic
   code src/utils.test.ts  # Or update test expectations
   

2. Test locally

   npm test -- src/utils.test.ts
   # Or the specific test
   npm test -- src/utils.test.ts -t "parseConfig returns valid"
   

3. Commit changes

   git add src/
   git commit -m "Fix parseConfig test failure — ensure config validation works correctly"
   git push
   

4. Verify CI recheck

   # GitHub Actions auto-triggers on push
   # Or manually re-run:
   gh run rerun [RUN_ID]
   
   # Monitor status
   gh pr checks [PR]
   

Step 8: Re-check Status

After changes, verify fixes:

gh pr checks [PR] --json state,conclusion

If still failing:

• Fetch new logs
• Repeat analysis
• Consider flaky test vs. actual issue

If passing:

✅ All checks passing!
Ready to merge or request review.

Common Failure Patterns

Troubleshooting

Output

Deliver:

1. Failure Summary with logs excerpt
2. Likely Root Cause (educated guess from logs)
3. Fix Plan (using plan skill)
4. After approval: Applied changes with commit link
5. Re-check results (passing or still failing)