configure-ci

Use when setting up CI/CD for a frontend project — a least-privilege GitHub Actions pipeline (install, lint, typecheck, audit, test, build, e2e, bundle budget) that gates merges, plus preview deploys

SKILL.md

GitHub

Configure CI

The pipeline that makes "CI is the real gate" true: every PR must pass lint, types, tests, build, and e2e before merge, and gets a preview to click through where the host supports it.

1. Audit current state

cat .claude/stack-profile.md 2>/dev/null || cat ~/.claude/stack-profile.md 2>/dev/null   # package_manager, frontend.framework, hosting, ci
ls .github/workflows/ .github/actions/ netlify.toml vercel.json vercel.ts Caddyfile .nvmrc 2>/dev/null
grep -E '"(lint|format|test|build|e2e|size)"' package.json 2>/dev/null   # the scripts CI will call
grep -rn "uses:" .github/workflows 2>/dev/null | grep -vE "@[0-9a-f]{40}" | grep -v "uses: \./"   # unpinned actions

Read from the profile: package_manager (this skill is written for pnpm — for another manager swap the install line and drop pnpm/action-setup: npm ci, bun install --frozen-lockfile, yarn install --immutable), frontend.framework (the typecheck script already picks tsc -b or vue-tsc -b), hosting (step 4), ci (must be github-actions; anything else: stop and say so). Test commands come from package.json scripts, so tests.layout does not change the workflow.

Prerequisites: configure-linting (Biome), configure-test-stack (Vitest + Playwright), a Node version in .nvmrc (scaffold-frontend-project). The bundle-budget step expects size-limit from optimize-performance.

2. Decide

  • No workflow → full setup. Partial → add missing jobs. Present → confirm jobs cover lint, types, audit, test, build, e2e, and that every action is pinned.
  • Containerised deploy to a server (self-hosted)? The deploy half belongs to set-up-delivery-pipeline; this skill owns the PR checks only.

3. The pipeline

Shared setup as a local composite action, so the three jobs do not repeat it. Action refs are full commit SHAs with the version in a comment (ci-patterns.md); Dependabot bumps both.

# .github/actions/setup/action.yml
name: Setup
description: pnpm, Node from .nvmrc, frozen-lockfile install
runs:
  using: composite
  steps:
    - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
    - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
      with:
        node-version-file: .nvmrc
        cache: pnpm
    - run: pnpm install --frozen-lockfile
      shell: bash
# .github/workflows/ci.yml
name: CI
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

jobs:
  quality:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup
      - run: pnpm exec biome ci .
      - run: pnpm typecheck
      - run: pnpm audit --prod --audit-level high

  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup
      - run: pnpm exec playwright install --with-deps chromium
      - run: pnpm test
      - run: pnpm exec playwright test
      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        if: ${{ !cancelled() }}
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 14

  build:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: ./.github/actions/setup
      - run: pnpm build
      - run: pnpm exec size-limit

Match script/binary names to package.json (pnpm test = Vitest; drop size-limit unless optimize-performance wired it). pnpm/action-setup reads the pnpm version from package.json's packageManager field (set by scaffold-frontend-project); without that field, pin it with with: { version: <n> } — which means editing the setup/action.yml snippet above, since it hardcodes no version. Typecheck needs the generated route tree: commit src/routeTree.gen.ts (set-up-routing), or pnpm typecheck fails in a clean checkout. Run pnpm audit in quality only for production deps: a dev-only advisory should not block a hotfix. pnpm audit queries the registry, so make the step non-blocking (continue-on-error: true) if the registry is unreliable or requires auth.

4. Preview deploys — branch on hosting

Profile hosting / evidence Branch
netlify, or netlify.toml 4a
vercel, or vercel.json / vercel.ts 4b
hetzner, ionos, Caddyfile 4c
supabase, none, unknown Ask one question: where is the SPA served from?

In every branch the host builds the preview with its own Git integration. Do not duplicate the build inside the workflow.

4a. Netlify

Enable Deploy previews in the Netlify UI (Site → Build & deploy). Add the build config to netlify.toml (set-up-security-headers owns the [[headers]] block, so merge):

[build]
  command = "pnpm build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

4b. Vercel

Import the repo in Vercel once; every PR push then gets a preview URL, and main deploys to production. Vite is auto-detected. Add only the SPA fallback to vercel.json (set-up-security-headers owns headers; merge):

{ "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

Keep Deployment Protection on for previews of anything not public. Setup, env vars, domains: ../../infra/deploy-to-vercel/SKILL.md.

4c. Self-hosted

There is no built-in preview. CI gates the merge; the deploy (image build, push, rollout, TLS) is ../../infra/deploy-to-hetzner/SKILL.md and set-up-delivery-pipeline. A per-PR preview stack is optional and costs a server slot per open PR — add it when reviewers need to click, not by default.

5. Make it the gate

Branch protection lives in GitHub settings, not the repo: Settings → Branches → protect main → require quality, test, build. On Netlify/Vercel also require the host's deploy check if the preview must work before merge. Without protection, CI is advisory. Document it — a committed file cannot set it. Also enable Dependabot for github-actions (set-up-security-headers step 6).

6. Verify

Open a PR: the three jobs run and pass; Netlify/Vercel post a preview link. Push a lint error → quality fails → merge is blocked. grep -rn "uses:" .github/workflows | grep -vE "@[0-9a-f]{40}" prints nothing except ./ paths.

References

  • ./ci-patterns.md — CI-as-the-gate, --frozen-lockfile, SHA-pinned actions, least-privilege token, caching, the bundle budget, preview-per-PR per host, when to deviate.
  • ../configure-linting/SKILL.md — the lint/format the pipeline runs.
  • ../configure-test-stack/SKILL.md — Vitest + Playwright.
  • ../set-up-security-headers/SKILL.md — shares the host config file (owns the headers; this skill owns build + fallback).
  • ../../infra/set-up-delivery-pipeline/SKILL.md — the build-once, promote-by-digest pipeline for server deploys.