# Fix CI > Diagnose and fix a failing CI run by pulling the actual failure logs (gh run view --log-failed), reproducing the failure locally, fixing the root cause rather than the symptom, and verifying green before and after pushing. Use when a GitHub Actions run is red, a PR check is failing, or CI passes locally but fails remotely. - Skill: `khaledsaeed18/fix-ci` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add khaledsaeed18/fix-ci` - Raw SKILL.md: https://api.skillmd.com/api/skills/khaledsaeed18/fix-ci/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: KhaledSaeed18 (https://skillmd.com/u/khaledsaeed18) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/khaledsaeed18/fix-ci --- Fix the failure CI actually reported, not the one you assume it hit. The log line that failed the job is evidence; everything else is guessing. Pull it first, reproduce it locally second, and only then change code. ## Step 1: Get the real failure ```bash # What failed, and on which commit gh run list --limit 10 gh run view --log-failed 2>&1 | tail -80 ``` Read the failed step's output completely. Identify: the failing step name, the exact error, and whether the failure is in *your change* or in the pipeline itself (setup step, cache, runner image, flaky network). If several jobs failed, find the first failure in dependency order; downstream jobs often fail as a consequence. If the run belongs to a PR, also check which check is required and whether the failure is new to this branch: ```bash gh pr checks git log --oneline origin/main..HEAD ``` ## Step 2: Reproduce locally Run the failing step's actual command from the workflow file, not your usual local equivalent: ```bash # Read the workflow to get the exact command and environment cat .github/workflows/.yml ``` - **Reproduces locally:** it is a code problem. Debug it normally (the `systematic-debugging` skill applies) and fix the root cause. - **Passes locally, fails in CI:** the difference is environmental. Compare in this order: dependency install mode (`--frozen-lockfile` vs a loose local install), Node/tool versions (CI pins one; check yours), OS differences (case-sensitive paths, line endings), missing env vars or secrets, and cache staleness. State which difference explains the failure before changing anything. - **Not reproducible and clearly infrastructure** (runner network blip, rate limit, timeout on a step that touches nothing you changed): rerun once with `gh run rerun --failed`. If it fails the same way twice, it is not flake; go back to evidence. ## Step 3: Fix the cause, not the check Make the smallest change that addresses the named root cause. Things that are not fixes: - Deleting or skipping the failing test to make CI green. - Loosening an assertion until it passes. - Adding `continue-on-error` or removing the step. - Bumping a timeout without knowing why the step got slower. Any of these may be *proposed* to the user with justification, but never applied silently as "the fix". ## Step 4: Verify green, twice 1. **Locally:** run the exact failing command again and confirm it passes, plus the project's full check suite so the fix didn't break a sibling. 2. **Remotely:** push, then watch the run to completion rather than assuming: ```bash gh run watch --exit-status ``` Report the root cause, the fix, and the green run link. If the failure was flake, say so explicitly and note the rerun that confirmed it.