golid / rules

---
description: CI workflow patterns for GitHub Actions
globs:
  - .github/workflows/*.yml
  - codecov.yml
---
# CI Workflow Patterns

> **Thesis:** CI catches what developers forget: type errors, test regressions, stale generated types, and vulnerable dependencies. Jobs must not have cross-job dependencies.

## Job structure

| Job | Gate | Depends on |
|-----|------|------------|
| `changes` | always | — |
| `spec-drift` | always | — |
| `backend-unit` | `run_backend` | `changes` |
| `backend-integration` | `run_backend` | `changes`, `backend-unit` |
| `backend-coverage` | `run_backend` + unit + integration OK | `changes`, `backend-unit`, `backend-integration` |
| `frontend` | `run_frontend` | `changes` |
| `scaffold-verify` | `run_backend \|\| run_frontend` | `changes` |
| `e2e` | `run_e2e` + integration + frontend OK | `changes`, `backend-integration`, `frontend` |

`changes` uses `dorny/paths-filter@v4` to compute `run_backend`, `run_frontend`, `run_e2e`. Docs-only PRs (`docs/**`, `**/*.md` except `CHANGELOG.md`) run `changes` + `spec-drift` only — backend, frontend, scaffold, and E2E are skipped. **CHANGELOG-only** commits run backend + frontend (Codecov refresh) without E2E. `codecov.yml` sets `flag_management.default_rules.carryforward: true` so docs-only pushes keep the last report on HEAD.

Workflow needs `pull-requests: read` for paths-filter on PRs.

## Backend unit job checklist

- No PostgreSQL — unit tests only
- `go build` + `go vet` before tests
- golangci-lint: pin to a version compatible with the Go version in `go.mod`
- Unit tests split: pure packages without `-race` (apperror, config, pagination, retry, validate), then handler/middleware/observability/queue/service/testutil/wire with `-race`
- Both unit runs use shared `COVERPKG` env and merge into `coverage-unit.out`
- govulncheck: always run, fails CI on vulnerabilities
- Upload `coverage-unit.out` as artifact (not Codecov yet)

## Backend integration job checklist

- PostgreSQL service container with health check (`golid_test` database)
- Matrix shard: `handler` | `service` — each shard runs on a separate runner
- `go test -tags integration ./internal/${{ matrix.shard }}/... -race -count=1`
- Handler shard exits 0 with no packages when no handler integration tests exist — do not add skip hacks
- Set `TEST_DATABASE_URL` only — `testutil.SetupTestDB()` panics if unset (no `DATABASE_URL` fallback)
- `TEST_MIGRATIONS_PATH: ${{ github.workspace }}/backend/migrations` — per-package schemas via testutil, no global migrate step
- Upload per-shard `coverage-integration-{shard}.out` as artifacts

## Backend coverage job checklist

- Downloads all `backend-coverage-*` artifacts and merges into `coverage.out`
- Codecov: `codecov/codecov-action@v6` with `skip_validation: true`, `slug: golid-ai/golid`, `-F backend` flag
- Runs only when unit and integration jobs both succeed

## Frontend job checklist

- Node 24 via `.nvmrc` (`node-version-file: ".nvmrc"`)
- `npm ci` (not `npm install`) for reproducible installs
- OpenAPI: duplicate path key grep, then `swagger-cli validate`, then `npm run generate:types` + typecheck (no committed-types diff gate)
- `npm run lint` before build
- `npm run build`
- `npm run test:coverage` (not `npm test` — the `test` script runs vitest in watch mode)
- Codecov: `codecov/codecov-action@v6` with `skip_validation: true`, upload `frontend/coverage/lcov.info` with `-F frontend` flag
- `npm audit --audit-level=high` with `continue-on-error: true` (transitive dep vulns shouldn't block PRs)

## E2E job checklist

- Gated on `run_e2e` — skipped for docs-only PRs
- `cp config/.env.example config/.env.local` — create env file before docker compose
- Pre-build backend image with `docker/build-push-action` + GHA cache (`scope=golid-e2e-backend`)
- Start stack via `docker compose -f docker-compose.yml -f docker-compose.ci-e2e.yml` (no `--build`)
- Wait for DB: poll `pg_isready` on the db container (not just backend `/ready`)
- Install `migrate` CLI + run migrations against the docker compose DB
- Seed data: `psql < backend/seeds/dev_seed.sql` via docker compose exec
- Wait for backend: poll `/ready` endpoint (not `/health` — readiness means DB is connected)
- Node 24 via `.nvmrc`; `npm ci` in frontend (Playwright needs `@playwright/test` from node_modules)
- Cache `~/.cache/ms-playwright`; on cache hit install deps + chromium only
- Playwright's `webServer` config starts the frontend dev server automatically — do NOT set `E2E_SKIP_SERVER`
- `config/.env.example` must be committed (check `.gitignore` exceptions) — CI copies it to `.env.local`
- Needs `actions: write` permission for BuildKit GHA cache

## Codecov config

Golid uses a fixed coverage floor (not `target: auto`):

- `codecov.yml`: `target: 80%`, `threshold: 2%`, `patch: off`
- Dual flags: `backend` (`backend/`) and `frontend` (`frontend/src/`) — uploads use `-F backend` / `-F frontend`
- `flag_management.default_rules.carryforward: true` — docs-only pushes keep the last report on HEAD
- Path fixes: `github.com/golid-ai/golid/backend/::backend/` for monorepo layout

Do not remove `flags:` from uploads — Codecov uses them to map coverage to the correct directories.

## Spec-Drift Gate

`scripts/check_spec_drift.sh [base_ref]` reports `internal/handler/*.go` and `internal/service/*/*.go` files changed without a matching `docs/modules/<module>/spec.md` change. Default base is `origin/main`. Exit 0 = clean, exit 1 = drift.

Module mapping (Golid):

| Handler/service stem | Spec folder |
|---------------------|-------------|
| `auth`, `auth_password`, `auth_verify` | `auth` |
| `user` | `users` |
| `feature` | `feature` |
| `sse`, `email`, `wire`, etc. | ignored (no module spec) |

Escape hatch: `[skip-spec(<module>): <reason>]` or `[skip-spec: <reason>]` in any commit message in the range.

**CI wiring** — the `spec-drift` job runs on every push and PR. All three scripts fail the job on drift (no `continue-on-error`):

1. `scripts/check_spec_drift.sh`
2. `scripts/check_citation_freshness.sh`
3. `scripts/check_rule_health.sh` — validates Cursor rules (thesis lines, globs)

Local usage: `scripts/check_spec_drift.sh origin/main` before opening a PR. Pairs with `slice-and-ship` contract closeout and `git-commits` pre-commit check.

## Common mistakes

- **Missing `npm ci`** — any step that runs `npx` with a project dependency needs `npm ci` first. `npx` without node_modules downloads a standalone version that can't find project packages.
- **golangci-lint + new Go versions** — golangci-lint must be built with a Go version >= the one in `go.mod`. After a Go upgrade, check if a compatible golangci-lint version exists. If not, `continue-on-error: true` until one is released.
- **Gitignored env files** — `config/.env.example` is needed by the E2E job. The `.gitignore` pattern `config/.env.*` catches it — add `!config/.env.example` exception.
- **Database name** — CI uses a separate test database. Keep the name consistent with the project (`golid_test`). Update if the project is renamed.
- **Stale generated types** — `npm run generate:types` produces `frontend/src/lib/api.generated.ts` from `backend/openapi.yaml`. Regenerate locally after any spec change; CI validates via typecheck after fresh generation.
- **Tests pass but typecheck fails** — `vitest run` executes JavaScript at runtime and does not check TypeScript types. Always run `npm run typecheck` locally before pushing frontend test files. Bad imports (non-existent exports, type-only imports used as values) pass at runtime but fail `tsc`.
- **testutil requires TEST_DATABASE_URL** — `testutil.SetupTestDB()` panics if `TEST_DATABASE_URL` is unset (refuses `DATABASE_URL` fallback because `CleanAllTables` would wipe the dev DB). CI sets `TEST_DATABASE_URL=postgres://test:test@localhost:5432/golid_test?sslmode=disable`. Local integration tests need the same env var pointing at a safe-to-wipe DB (e.g. `golid_test`).