ci-hygiene

Files (1)

• SKILL.md

SKILL.md (first lines)

# CI Hygiene — make CI deterministic and safe

Claude Code in CI is a different beast than interactive CC. Different auth, different performance profile, different failure modes. This skill enforces the rules that keep pipelines deterministic, secure, and reproducible.

## When to activate

- Editing `.github/workflows/*.yml`, `.gitlab-ci.yml`, `.circleci/config.yml`, other CI config
- Editing `Dockerfile`, `docker-compose.yml`, `Containerfile`
- Editing `justfile`, deploy scripts, release automation
- User asks: "set up CI", "add GitHub Action", "dockerize", "deploy script"
- Review of changes touching any of the above

## Tool dispatch

| Concern | Tool |
|---|---|
| Check current CI config for anti-patterns | `ast-grep` (structural scan), `Grep` for specific patterns (`@latest`, unpinned tags) |
| Look up current versions of CI actions | `docfork` MCP (needs `DOCFORK_API_KEY`) for tool docs |
| Reference similar OSS CI configs | `deepwiki` MCP |
| Dependency vuln scan of the CI image | `snyk_container_scan` (snyk MCP) if Dockerfile in scope |
| IaC scan for Terraform/K8s/etc. | `snyk_iac_scan` |
| Past CI decisions on this repo | `/claude-mem:mem-search "CI"` |
| Plan a large CI overhaul | `/claude-mem:make-plan` + `/claude-mem:do` |

## The rules (enforced on every edit)

### 1. Claude Code in CI uses `--bare`

Interactive CC has hooks, LSP, plugin sync, CLAUDE.md auto-discovery, auto-memory, and keychain reads. In CI, all of that is overhead or a security hazard. `--bare` disables all of it and sets `CLAUDE_CODE_SIMPLE=1`.

```yaml
# ✅ Correct
- run: claude --bare -p "Review this PR" --system-prompt-file .github/prompts/review.md

# ❌ Wrong
- run: claude -p "Review this PR"
```

### 2. API key for CC in CI, NOT a Max subscription

Since the April 4, 2026 enforcement, using a Max subscription in CI will fail. CI must use a dedicated `ANTHROPIC_API_KEY` (or Bedrock/Vertex/Foundry equivalent) stored in CI secrets.

```yaml
# ✅ Correct
env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# ❌ Wrong — relies on interactive OAuth/keychain
```

### 3. Pin every version

No `@latest`, no `@v*`, no floating tags. Every GitHub Action, every Docker base image, every tool install gets a concrete version (ideally a SHA for Actions, a digest for containers).

```yaml
# ✅ Correct
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1

# ❌ Wrong
uses: actions/checkout@v4
```

```dockerfile
# ✅ Correct
FROM node:22.14.0-bookworm-slim@sha256:...

# ❌ Wrong
FROM node:latest
```

### 4. `justfile` over raw commands in pipeline yaml

Don't hardcode raw `bun test`, `docker build`, etc. in the workflow yaml. Put the command in `justfile` and have the pipeline call `just <target>`. Keeps the pipeline portable; the developer can run the exact same thing locally.

```yaml
# ✅ Correct
- run: just test-ci

# ❌ Wrong (duplicates intent across local + CI)
- run: bun install --frozen-lockfile && bun test
```

### 5. Secrets only in CI secrets manager

Never in env files, never committed, never echoed in logs. Mask them in `set -x` flows.

### 6. Reproducible builds

Lock files must be committed and CI must install from the lock: `bun install --frozen-lockfile`, `npm ci` (not `npm install`), `cargo build --locked`, `uv sync --frozen`, etc.

### 7. Timeouts on everything

Every CI job gets a `timeout-minutes:` (GitHub Actions) or equivalent. Unbounded jobs are a runaway cost risk and obscure infrastructure issues.

### 8. Sandbox layer for any agentic work

If a CI job lets Claude Code or another agent run commands, wrap the agent in `container-use` (per-agent Docker isolation with git-branch scoping) — do NOT give it raw runner access.

### 9. `claude-mem` in deployed envs binds to 127.0.0.1

If any deployment runs claude-mem, confirm it's bound to 127.0.0.1 — never 0.0.0.0 (port 37777 is the risk). This applies mostly to self-hosted dev-container setups.

### 10. Concurrency controls on expensive workflows

`concurrency: group: ... cancel-in-progress: true` on long-running workflows so a new push cancels the stale one. Prevents pipeline backups.

## Workflow

### Phase 1 — Inventory

Before editing, read the current file(s). Summarize what's there. Note every line that violates a rule above.

### Phase 2 — Classify the change

- **Additive** (new job, new step) → apply rules to the new code only. Don't scope-creep into fixing existing violations.
- **Refactor** (rewriting the CI) → opportunity to fix all violations. Do it in one pass with explicit approval.
- **Fix** (broken CI) → minimum change to unblock. File a follow-up note for the unrelated violations.

### Phase 3 — Apply and verify

From youssefKadaouiAbbassi/yka-code, MIT.

More from youssefKadaouiAbbassi/yka-code