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.mdskills/frontend/configure-ci/SKILL.md
GitHubConfigure 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.