Setup Ci

---
name: setup-ci
description: Analyze a GitHub repository and propose or improve a GitHub Actions CI setup with clearly separated jobs — one job per concern — so each check shows independently in the GitHub PR and Actions UI. Global and project-agnostic. Trigger when the user says "set up CI", "setup-ci", "add GitHub Actions", "propose CI jobs", "improve my CI", "add CI pipeline", "set up GitHub Actions workflow", "create GitHub Actions tests", or "suggest CI checks". SKIP when the user is asking about a non-GitHub CI system (Jenkins, CircleCI, GitLab CI) — this skill is GitHub Actions only.
---

# Set up GitHub Actions CI

Project-agnostic, global skill. It scans any GitHub repository, reads and audits any
existing `.github/workflows/` files, and proposes a clean GitHub Actions CI setup where
**each concern is a separate job** — so every check gets its own pass/fail indicator in
the GitHub PR and Actions UI, making it easy to pinpoint exactly what broke.

It pairs with `/propose-automation`: that skill handles the broader Claude Code automation
layer; this one focuses exclusively on the GitHub Actions CI pipeline.

## Operating principles (apply throughout)

1. **Separate jobs, not steps.** A job-per-concern means each check is independently
   retryable, cancellable, and visible in GitHub's status checks. Never bundle unrelated
   checks into one job just because it is convenient.
2. **Audit before rewrite.** If `.github/workflows/` already exists, read it first.
   Propose targeted improvements (missing jobs, missing caching, missing concurrency
   control, overly broad permissions) rather than replacing it wholesale.
3. **Best-practice defaults every new workflow should include:**
   - `on: push` + `on: pull_request` + `workflow_dispatch` (manual runs from GitHub UI)
   - `concurrency: group: ${{ github.workflow }}-${{ github.ref }}, cancel-in-progress: true`
   - `permissions: contents: read` at workflow level (least-privilege GITHUB_TOKEN)
   - `timeout-minutes` on every job (prevent stuck runners burning quota)
   - Dependency caching via the setup action's built-in `cache:` option, or `actions/cache`
4. **Propose only; never scaffold without approval.** The proposal step is always separate
   from writing files.
5. **Post-scaffold checklist always fires.** After writing any workflow file, remind the
   user about required status checks in branch protection, the README badge, and Dependabot.

## Procedure

### 1. Orient (scan)
- Check `.github/workflows/` for existing workflow files; read them fully if present.
- Identify the stack from manifests: `package.json`, `pyproject.toml`, `go.mod`,
  `Cargo.toml`, `Makefile`/`justfile`, `Dockerfile`, etc.
- Look for test/lint/build commands: `scripts` in `package.json`, `[tool.pytest]`,
  `.eslintrc*`, `tsconfig.json`, `ruff.toml`, `.shellcheck*`, `requirements*.txt`, etc.
- Skim the directory tree and `git log --oneline -20` to understand what kinds of changes
  land frequently.
- For large or unfamiliar repos, delegate the sweep to the `Explore` agent and work from
  its summary to keep the main context clean.
- Note stack signals that imply specific jobs: TypeScript → type-check; shell scripts →
  shellcheck; Python → ruff/mypy; Docker → build check; etc.

### 2. Find gaps (ask)
Ask 2–3 targeted questions — treat scan-based hypotheses as things to confirm, not
conclusions. Example angles:
- "Do you have a test command, and should it run on every PR?"
- "Are there integration or E2E tests that should run separately from unit tests?"
- "Any checks that currently get skipped or forgotten before merging?"
Adapt questions to what the scan reveals (e.g., skip the test question if a test command
is clearly wired up already with an existing CI job covering it).

### 3. Propose (ranked jobs — do NOT scaffold yet)
Present a ranked list of separate jobs. For each job:
- **Job name** (the `name:` value that appears in GitHub UI) + one-line purpose
- What command it runs
- Why it deserves its own job (what failure mode it isolates)
- Any best-practice additions (cache, matrix, artifacts)
- ROI rationale (frequency, error-reduction, time-to-detect)

Group the proposal into categories:
- **Core checks** (lint, type-check, test, build) — propose first
- **Quality gates** (coverage threshold, security scan, doc sync) — propose if justified
- **Infrastructure** (caching strategy, concurrency block, permissions, timeouts) — always include
- **Extras** (badge, Dependabot, `workflow_dispatch`) — list briefly at the end

Include a **"Not proposed / deferred"** section naming what you intentionally left out
and why (e.g., "E2E tests — no Playwright/Cypress config found; add when the suite exists").

Building nothing in this step is correct.

### 4. Scaffold (only what the user approves)
For each approved item:
- Write or update `.github/workflows/ci.yml` (default) — or a separate file if the user
  approves a concern that belongs in its own workflow (e.g., `release.yml`, `deploy.yml`).
- Apply the best-practice defaults from operating principle 3 to every file written.
- Use the exact job `name:` values from the proposal — those are what appear in GitHub's
  required-status-checks dropdown; renaming them later breaks branch protection rules.
- For matrix strategies, prefer explicit version arrays over `latest` aliases so new
  runtime releases don't silently break CI.
- Reference official actions at pinned major versions (`actions/checkout@v4`, not `@main`).

### 5. Post-scaffold checklist (always run after any write)
Present this checklist every time a workflow file is written:

**Required status checks (important):**
> GitHub → repo Settings → Branches → your branch → Edit → "Require status checks to pass"
> → add each job by its exact `name:` value. Without this step, the jobs run but do not
> block merges.

**README badge (offer):**
Provide the badge markdown for the user to paste:
`![CI](https://github.com/<owner>/<repo>/actions/workflows/ci.yml/badge.svg)`

**Dependabot for Actions (offer):**
Offer to create `.github/dependabot.yml` to keep action versions updated automatically:
```yaml
version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
```

## Guardrails
- Propose in step 3; write files only after explicit approval in step 4. Never auto-scaffold.
- If existing workflows are present, audit and improve — never silently replace.
- Always apply the best-practice defaults (concurrency, permissions, timeouts, caching)
  to every workflow file written.
- Always run the post-scaffold checklist after writing any workflow file.
- Use pinned major-version action references (`@v4`, not `@main` or `@latest`).
- Keep job `name:` values stable after writing — they become required status check keys.
- Never fabricate stack facts; base all proposals solely on evidence found in step 1.
- This skill is GitHub Actions only — if the user is on Jenkins, CircleCI, GitLab CI, etc.,
  decline gracefully and name the right tool.