GitHub CI Fix Skill

A Claude Code skill for diagnosing and fixing failing CI checks on GitHub pull requests — fetching action logs, identifying failure root causes, implementing fixes, and verifying the CI passes.

When to Use This Skill

Choose this skill when:

• A PR has failing CI checks that need investigation
• GitHub Actions workflow logs need analysis for error diagnosis
• Test failures in CI need to be reproduced and fixed locally
• Build errors or linting failures block PR merging
• CI configuration needs debugging or updating

Consider alternatives when:

• You need to set up CI from scratch (use a GitHub Actions skill)
• You need to fix application bugs unrelated to CI (just debug normally)
• You need to configure deployment pipelines (use a deployment skill)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add gh-fix-ci

# Diagnose and fix failing CI
claude "fix the failing CI checks on this PR"

# View CI status
claude "show me the CI failures on the current PR"

Copy
# Check CI status on current PR
gh pr checks

# View failed workflow run logs
gh run view --log-failed

# List recent workflow runs
gh run list --limit 5

Core Concepts

CI Diagnosis Workflow

Step	Action	Tool
1. Identify	Find which checks are failing	gh pr checks
2. Fetch Logs	Get detailed failure output	gh run view --log-failed
3. Analyze	Extract actionable error from logs	Parse log output
4. Reproduce	Run the same check locally	Local test/lint/build
5. Fix	Implement the fix	Edit code
6. Verify	Confirm fix works locally	Run check again
7. Push	Push fix and monitor CI	git push, gh pr checks --watch

Common CI Failure Types

Failure	Cause	Fix
Test failure	Code change broke a test	Fix code or update test
Lint error	Style violation introduced	Run linter with --fix
Type error	TypeScript compilation failure	Fix type annotations
Build failure	Import or dependency issue	Fix imports, update deps
Timeout	Test or build exceeded time limit	Optimize or increase limit
OOM	Process ran out of memory	Reduce memory usage or increase limit

Log Analysis

Copy
# Get the run ID for the failed check
RUN_ID=$(gh run list --status failure --limit 1 --json databaseId --jq '.[0].databaseId')

# View the full log for a failed job
gh run view $RUN_ID --log-failed

# Download logs for offline analysis
gh run view $RUN_ID --log > ci-failure.log

# Watch for CI completion after pushing a fix
gh pr checks --watch

Configuration

Parameter	Type	Default	Description
auto_detect_pr	boolean	true	Find PR for current branch automatically
reproduce_locally	boolean	true	Try to reproduce failure locally before fixing
watch_after_push	boolean	true	Monitor CI after pushing fix
max_log_lines	number	200	Lines of log to analyze per failed step
retry_flaky	boolean	false	Retry the workflow if failure appears flaky

Best Practices

1. Read the full error message, not just the first line — CI failures often have the real error buried in the middle of the log; the first line is often a generic wrapper message.

2. Reproduce locally before pushing a fix — run the same command that CI runs (npm test, npm run lint, npm run build) locally to verify your fix before pushing and waiting for CI.

3. Fix the root cause, not the symptom — if a test fails because of a race condition, fix the race condition rather than adding a retry or skipping the test.

4. Watch CI after pushing the fix — use gh pr checks --watch to monitor the CI run in real-time rather than pushing and checking back later.

5. Check if the failure is flaky before investigating deeply — if the same CI step passed on the previous commit without code changes, it might be a flaky test. Re-run the workflow first before debugging.

Common Issues

CI fails but tests pass locally — Environment differences between local and CI are the most common cause. Check Node.js version, OS differences (Linux vs macOS), timezone settings, and environment variables that CI has but local doesn't.

CI timeout on large test suite — Split tests into parallel jobs using matrix strategy in GitHub Actions. If a single test is slow, investigate whether it's making real network calls (should be mocked) or waiting on timeouts.

Flaky tests cause intermittent CI failures — Identify flaky tests by checking if the same test fails inconsistently across runs. Quarantine flaky tests into a separate job that doesn't block merging, and fix the root cause (usually race conditions or time-dependent assertions).