---
name: fix-failing-ci-checks
description: 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.
license: Apache-2.0
compatibility: Needs the GitHub CLI (gh) logged in with repo and workflow scopes
metadata:
  category: debugging
  tags: "ci,github-actions,debugging"
  author: johnny-bravo
  version: "1.0"
  updated: "2026-11-02"
  status: published
  aliases: "red ci, failing checks, github actions failed"
  source_url: "https://github.com/openai/skills/tree/49f948faa9258a0c61caceaf225e179651397431/skills/.curated/gh-fix-ci"
  source_license: Apache-2.0
  copyright: "Copyright (c) OpenAI (openai/skills, gh-fix-ci); Apache License 2.0 text in LICENSE.txt"
  original_author: "OpenAI (openai/skills, gh-fix-ci)"
  modified: "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."
  imported_on: "2026-11-02"
---

# Fix failing CI checks

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.