ci-fix

jMerta's avatarfrom jMerta

Fix GitHub Actions CI failures using GitHub CLI (gh): inspect runs/logs, identify root cause, patch workflows/code, rerun jobs, and summarize verification. Use when GitHub Actions CI is failing or needs diagnosis.

⭐90stars🔀6forks📁View on GitHub🕐Updated Jan 2, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill automates the troubleshooting and resolution of GitHub Actions CI failures. By leveraging the GitHub CLI (gh), it enables agents to programmatically inspect failing logs, identify root causes, apply code or workflow patches, and verify fixes through targeted reruns, significantly reducing the time to restore green builds.

Use Cases

  • 1. Automated CI Failure Diagnosis: Rapidly analyze verbose logs and failed steps from GitHub Actions to pinpoint the exact cause of build breaks without manual log diving.
  • 2. Workflow Configuration Repair: Detect and fix misconfigurations in .github/workflows files, such as incorrect environment variables, permission issues, or deprecated action versions.
  • 3. Flaky Test Management: Identify non-deterministic failures and use targeted reruns for specific failed jobs to confirm stability and reduce developer friction.
  • 4. Rapid Patch Verification: Automatically implement minimal code fixes and trigger 'gh run rerun --failed' to verify the solution in the actual CI environment.
nameci-fix
description"Fix GitHub Actions CI failures using GitHub CLI (gh): inspect runs/logs, identify root cause, patch workflows/code, rerun jobs, and summarize verification. Use when GitHub Actions CI is failing or needs diagnosis."

CI fix (GitHub Actions)

Goal

  • Get CI green quickly with minimal, reviewable diffs.
  • Use gh to locate failing runs, inspect logs/artifacts, rerun jobs, and confirm the fix.

Inputs to ask for (if missing)

  • Repo (OWNER/REPO) and whether this is a PR or branch build.
  • Failing run URL/ID (or PR number / branch name).
  • What "green" means (required workflows? allowed flaky reruns?).
  • Any constraints (no workflow edits, no permission changes, no force-push, etc.).

Workflow (checklist)

  1. Confirm gh context
    • Auth: gh auth status
    • Repo: gh repo view --json nameWithOwner -q .nameWithOwner
    • If needed, add -R OWNER/REPO to all commands.
    • If gh is not installed or not authenticated, tell the user and ask whether to install/authenticate or proceed by pasting logs/run URLs manually.
  2. Find the failing run
    • If you have a run URL, extract the run ID: .../actions/runs/<id>.
    • Otherwise:
      • Recent failures: gh run list --limit 20 --status failure
      • Branch failures: gh run list --branch <branch> --limit 20 --status failure
      • Workflow failures: gh run list -w <workflow> --limit 20 --status failure
    • Open in browser: gh run view <id> --web
  3. Pull the signal from logs
    • Job/step overview: gh run view <id> --verbose
    • Failed steps only: gh run view <id> --log-failed
    • Full log for a job: gh run view <id> --log --job <job-id>
    • Download artifacts: gh run download <id> -D .artifacts/<id>
  4. Identify root cause (prefer the smallest fix)
    • Use references/ci-failure-playbook.md for common patterns and safe fixes.
    • Prefer: deterministic code/config fix > workflow plumbing fix > rerun flake.
  5. Implement the fix (minimal diff)
    • Update code/tests/config and/or .github/workflows/*.yml.
    • Keep changes scoped to the failing job/step.
    • If changing triggers/permissions/secrets, call out risk and get explicit confirmation.
  6. Verify in GitHub Actions
    • Rerun only failures: gh run rerun <id> --failed
    • Rerun a specific job (note: job databaseId): gh run view <id> --json jobs --jq '.jobs[] | {name,databaseId,conclusion}'
    • Watch until done: gh run watch <id> --compact --exit-status
    • Manually trigger: gh workflow run <workflow> --ref <branch>

Safety notes

  • Avoid pull_request_target (and any change that runs untrusted fork code with secrets) unless the user explicitly requests it and understands the security tradeoffs.
  • Keep workflow permissions: least-privilege; don’t broaden token access “just to make it pass”.

Deliverable (paste in chat / PR)

  • Summary: ...
  • Failing run: <link/id> (job/step)
  • Root cause: ...
  • Fix: ...
  • Verification: commands + new run link/id
  • Notes/risks: ...