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

Pattern	Indicator	Fix
Timeout	"execution timeout after 300s"	Increase timeout or optimize code
Missing dep	"Cannot find module 'x'"	Add missing package or import
Flaky test	"Intermittent failures"	Add retry, improve timing, mock randomness
Env var missing	"process.env.API_KEY undefined"	Add secret to Actions workflow
Type error	"Property 'x' does not exist on type 'y'"	Fix TypeScript type annotations
Permission denied	"Access denied to /path"	Fix file permissions or paths

Troubleshooting

Issue	Solution
Can't fetch logs	Verify gh auth with gh auth refresh --scopes repo,workflow
Run ID not found	Use gh pr checks [PR] to get correct run ID
External CI system	Report details URL only; out of scope
Still can't debug	Try running test locally first to narrow scope

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)