Fix errors · Skill

Fix failing CI checks

fix-failing-ci-checks

Diagnoses red checks with the gh CLI - list what failed, pull the failed GitHub Actions job log, find the first real error, reproduce it locally, then propose a fix and apply it only after approval. Use when CI or pull request checks fail, a build job turns red, or code that works locally breaks in CI.

Works with: Any AI Not yet model-tested; testing Jan 2027

View raw SKILL.mdInstall

Paste it into ChatGPT, Claude, Gemini or any AI chat, then tell it about your project. How it works

Install in Claude Code, Cursor or Codex (optional)

Only for AI coding tools that read skill folders. Run one line in a terminal, in your project folder. It downloads this skill's text files from TheSkillVault and nothing else; you can read them first with “View raw SKILL.md”.

Claude Code (all your projects)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-failing-ci-checks/raw' -o ~/'.claude/skills/fix-failing-ci-checks/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-failing-ci-checks/files/LICENSE.txt' -o ~/'.claude/skills/fix-failing-ci-checks/LICENSE.txt'

Cursor (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-failing-ci-checks/raw' -o '.cursor/skills/fix-failing-ci-checks/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-failing-ci-checks/files/LICENSE.txt' -o '.cursor/skills/fix-failing-ci-checks/LICENSE.txt'

Codex and other Agent Skills tools (this project)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-failing-ci-checks/raw' -o '.agents/skills/fix-failing-ci-checks/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/fix-failing-ci-checks/files/LICENSE.txt' -o '.agents/skills/fix-failing-ci-checks/LICENSE.txt'

Or connect the whole library over MCP

Add TheSkillVault to Cursor or add this to your app's MCP settings (read-only; help):

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

When a pull request turns red, read the log before guessing. Most failures are one line, buried under hundreds.

When to use

  • A pull request shows failing checks on GitHub.
  • A GitHub Actions job fails but the code works on your machine.
  • You want a short summary of why CI failed before fixing anything.

When not to use

  • You are setting up CI for the first time. Use configure-github-actions-ci.

Steps

  1. Check the CLI: gh auth status. If logged out, run gh auth login yourself.
  2. Find the PR: gh pr view --json number,url on the branch, or use the number you were given.
  3. List checks: gh pr checks <pr>. Note each failing check and its link.
  4. For each GitHub Actions failure, take the run id from the link and run gh run view <run-id> --log-failed.
  5. Scroll to the first error, not the last. Later errors are usually knock-on effects.
  6. Reproduce locally with the same command and versions the workflow uses (Node or Python version, lockfile, env vars).
  7. Write a short summary: check name, the error line, the likely cause.
  8. Propose a fix plan and wait for a yes before changing code.
  9. Apply the fix, run the same command locally, push, then re-run gh pr checks <pr>.

Common causes

  • Lockfile out of date, or npm install used where CI runs npm ci.
  • A different runtime version in CI than on your machine.
  • A missing secret or env var in the repository settings.
  • Tests that depend on time zone, order or network.
  • Lint or type errors your editor did not show.

Gotchas

  • Checks from other providers (Buildkite, CircleCI, Vercel) are not GitHub Actions logs. Report their link instead of guessing.
  • Never print secrets in a log to debug them. Check that the name exists, not its value.
  • Do not "fix" CI by deleting the failing test or disabling the job without asking.
  • A job still running has no full log yet. Wait, or fetch that job's log alone.

Portability

Works with any language or test runner. If you use GitLab or another CI, the same read-first, reproduce-locally loop applies with that tool's log command instead of gh.

Example prompt

"My PR's CI is red but tests pass locally. Find out why and suggest a fix before changing anything."

Done when

  • Every failing check has a one-line cause with the log line that proves it.
  • The fix was approved, reproduced locally and pushed.
  • gh pr checks shows all required checks passing.

---

Modified from "gh-fix-ci" in openai/skills (Apache-2.0). Changes by TheSkillVault are listed in the metadata above. See LICENSE.txt.

Bundled files

Licence

Adapted from OpenAI (openai/skills, gh-fix-ci) (Copyright (c) OpenAI (openai/skills, gh-fix-ci); Apache License 2.0 text in LICENSE.txt), Apache License 2.0. Modified by TheSkillVault on 2026-11-02: rewritten as beginner steps using plain gh commands; the bundled Python inspection script was not included; added a local-reproduction step, common causes, gotchas and done-when. Not the original file.

Licence: Apache License 2.0. Attribution when you reuse it: Based on work by OpenAI (openai/skills, gh-fix-ci) (Copyright (c) OpenAI (openai/skills, gh-fix-ci); Apache License 2.0 text in LICENSE.txt, Apache License 2.0), https://github.com/openai/skills/tree/49f948faa9258a0c61caceaf225e179651397431/skills/.curated/gh-fix-ci; adapted by TheSkillVault, https://theskillvault.ai