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:

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.