# Fix CI

> Diagnoses and fixes CI pipeline failures. Reads CI logs, identifies root cause, applies targeted fixes, and verifies locally before pushing. Structured approach prevents the common cycle of blind fix attempts.

- Skill: `gabrielmoreira/fix-ci` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/fix-ci`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/fix-ci/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gabrielmoreira/fix-ci

---


# Skill: Fix CI

## What This Skill Does

Provides a **structured debugging workflow for CI failures**. Instead of the common pattern of "read error → guess fix → push → wait → repeat", this skill enforces: analyze logs → identify root cause → reproduce locally → fix → verify locally → push once.

## When to Use

- When CI checks fail on a PR or push
- When the user says "CI is red" or "fix the pipeline"
- After `pr-ready` detects CI failures

Do NOT use this for writing new CI pipelines — use `ci-setup` for that.

## Execution Model

- **Always**: the primary agent runs this skill directly.
- **Rationale**: CI fixes require terminal access (running tests locally), file edits, and iterative debugging — all primary agent capabilities.
- **Token budget**: ~3-8k tokens depending on failure complexity.

## Workflow

### Step 1: Get CI Status

Determine which CI checks failed:

```bash
# For GitHub Actions
gh run list --limit 5
gh run view <run-id> --log-failed
```

If the user provides a run ID or URL, use that directly.

### Step 2: Categorize the Failure

CI failures fall into predictable categories:

| Category | Indicators | Typical Fix |
|----------|-----------|-------------|
| **Lint/Format** | eslint, ruff, prettier, markdownlint errors | Auto-fix or targeted code change |
| **Type Check** | tsc, mypy, pyright errors | Fix type annotations |
| **Test Failure** | pytest, jest, vitest failures | Fix test or implementation |
| **Build Failure** | compile errors, missing dependencies | Fix imports, install deps |
| **Config Error** | YAML syntax, invalid action version | Fix config file |
| **Environment** | missing secrets, wrong runner, timeout | Fix workflow config |
| **Dependency** | lockfile conflict, version mismatch | Update lockfile |

### Step 3: Extract Root Cause

Read the failed job's logs and identify:

1. **Which job failed** (name, step)
2. **The actual error message** (not just the summary)
3. **The file and line** (if applicable)
4. **Whether it's a flaky failure** (check if the same test passed on the previous run)

```bash
gh run view <run-id> --log-failed 2>&1 | tail -50
```

### Step 4: Reproduce Locally

Before fixing, verify the failure reproduces locally:

- **Lint**: run the same linter locally
- **Tests**: run the specific failing test
- **Build**: run the build command
- **Type check**: run the type checker

If it doesn't reproduce locally, the issue is environment-specific (secrets, runner version, caching).

### Step 5: Apply Fix

Apply the minimal fix for the identified root cause:

- **One fix per failure category**: don't mix lint fixes with test fixes
- **Smallest possible change**: avoid refactoring while fixing CI
- **Run the same check locally** after applying the fix

### Step 6: Verify Locally

Run the exact same commands that CI runs:

```bash
# Example for a typical project
npm run lint        # or: ruff check .
npm test            # or: pytest
npm run build       # or: python -m build
npm run typecheck   # or: mypy .
```

All must pass before pushing.

### Step 7: Push and Monitor

```bash
git add -A
git commit -m "fix: <category> — <what was wrong>"
git push
```

Then monitor the CI run:

```bash
gh run watch
```

## Rules

1. **Read logs first**: never guess at CI fixes. Always read the actual error output.
2. **Reproduce locally**: verify the failure before fixing. Pushing blind fixes wastes CI minutes and time.
3. **One category at a time**: fix lint issues separately from test failures. This makes the fix commit clear and revertable.
4. **Minimal fix**: do not refactor, optimize, or "improve" code while fixing CI. Fix only the failure.
5. **Verify before push**: run the same checks locally. Never push and hope.
6. **No built-in explore agent**: do NOT use the built-in `explore` subagent type.