name: "GitHub CI Fix Debugging" description: "Debug and fix failing GitHub PR checks by inspecting GitHub Actions logs, summarizing failure context, drafting fix plans, and implementing fixes after approval." version: 1.0.0 author: openai license: MIT tags: [github-actions, ci, debugging, pr-checks, fix] testingTypes: [integration] frameworks: [github-actions] languages: [yaml, typescript, javascript, python] domains: [devops] agents: [claude-code, cursor, github-copilot, windsurf, codex, aider, continue, cline, zed, bolt]

GitHub CI Fix Debugging

Use gh CLI to locate failing PR checks, fetch GitHub Actions logs for actionable failures, summarize the failure, propose a fix plan, and implement after explicit approval.

Prerequisites

Authenticate with the GitHub CLI:

gh auth login  # Ensure repo + workflow scopes
gh auth status  # Verify authentication

Workflow

1. Verify Authentication

gh auth status

If unauthenticated, ask the user to run gh auth login with repo + workflow scopes.

2. Resolve the PR

# Current branch PR
gh pr view --json number,url

# Or use a specific PR number
gh pr checks <pr-number>

3. Inspect Failing Checks

# List all PR checks with status
gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow

# For each failing check, get the run details
gh run view <run_id> --json name,workflowName,conclusion,status,url

# Fetch the logs
gh run view <run_id> --log

4. Scope Non-GitHub Actions Checks

• If detailsUrl is not a GitHub Actions run, label it as external
• Only report the URL for external providers (Buildkite, etc.)

5. Summarize Failures

For each failing check, provide:

• The failing check name
• The run URL
• A concise log snippet showing the actual failure
• Root cause analysis

6. Create a Fix Plan

Draft a concise plan including:

• What failed and why
• Proposed fix with specific file changes
• Impact assessment
• Request explicit approval before implementing

7. Implement After Approval

• Apply the approved plan
• Summarize diffs and changes made
• Run relevant tests locally if possible

8. Recheck Status

# After fixes, verify checks pass
gh pr checks <pr>

Common CI Failure Patterns

Test Failures

• Check test output for assertion errors
• Look for environment-specific issues
• Verify test data and fixtures

Build Failures

• Check dependency versions and lockfiles
• Verify TypeScript/compilation errors
• Check for missing environment variables

Lint/Format Failures

• Run linter locally to reproduce
• Apply auto-fix where possible
• Check for new rule violations

Timeout Issues

• Identify slow tests or builds
• Check for infinite loops or deadlocks
• Consider increasing timeout or optimizing