ci-github-actions

# CI with GitHub Actions Complete copy-paste workflows for Go and Node/TS live in `references/workflows.md` — read it when writing an actual workflow file. This file is the rules. ## Pipeline shape Default pipeline: **lint → typecheck → test → build**, as parallel jobs (they don't depend on each other's outputs) with `build` optionally `needs:` the rest if you want fail-fast economics. Trigger: ```yaml on: push: branches: [main] pull_request: ``` Don't run `push` on every branch *and* `pull_request` — that double-builds PR branches. ## Concurrency — cancel superseded runs Every CI workflow gets this; without it, ten pushes to a PR queue ten full runs: ```yaml concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true ``` For deploy workflows, keep the group but set `cancel-in-progress: false` (queue, don't kill mid-deploy). ## Permissions — least privilege Top of every workflow: ```yaml permissions: contents: read ``` Grant more only per-job, only what that job proves it needs (`pull-requests: write` for a comment bot, `id-token: write` for OIDC cloud auth, `packages: write` for pushing images). Never leave the org/repo default write-all doing the work implicitly. ## Pin third-party actions to SHA - Official `actions/*` and other heavily-trusted orgs: major tag is acceptable (`actions/checkout@v5`). - **Everything else: pin to a full commit SHA** with a version comment: ```yaml uses: some-org/some-action@3d1a2b... # v2.1.0 ``` Tags are mutable; a compromised action re-tagged at `v2` runs in your CI with your secrets. Dependabot/Renovate can bump SHAs for you — enable it. ## Caching - **Go**: `actions/setup-go@v6` with `cache: true` (default when a `go.sum` exists) — caches module and build cache. Don't hand-roll `actions/cache` for Go. - **Node/npm or yarn**: `actions/setup-node@v5` with `cache: npm` — caches the package cache (correct; don't cache `node_modules`). - **pnpm**: setup-node's `cache: pnpm` caches the pnpm store. Install pnpm first (`pnpm/action-setup`, SHA-pinned), then setup-node with `cache: pnpm`, then `pnpm install --frozen-lockfile`. - **bun**: `oven-sh/setup-bun` (SHA-pinned) has no built-in caching — pair with `actions/cache` on `~/.bun/install/cache`, key `bun-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/bun.lock') }}`, then `bun install --frozen-lockfile`. - Cache keys must include the lockfile hash — built-in caching does this for you. - Never cache build outputs between CI runs as a correctness shortcut; only as a measured optimization (Next.js `.next/cache` is the common legitimate case). ## Matrix — only when genuinely needed A matrix multiplies CI cost. Use one when you actually support multiple targets (a library testing Node 20/22, or linux+windows CLIs). An app deployed to one runtime tests on that one runtime version — pin it to the version production runs. ## Secrets - Secrets come from GitHub **Environments** (`environment: production` on the job), which gate them behind protection rules and reviewers — not from repo-wide secrets sprayed into every job. - CI jobs (lint/test/build) should need zero secrets. If a test needs a secret, question the test. - Never `echo` secrets, never pass them as CLI args (visible in process lists/logs). Prefer OIDC (`id-token: write` + cloud role assumption) over long-lived cloud keys. - `pull_request_target` + checkout of PR head = classic secret-exfiltration hole. Don't use `pull_request_target` unless you know exactly why. ## Monorepo path filters Scope workflows to what changed: ```yaml on: pull_request: paths: - "services/api/**" - ".github/workflows/api.yml" ``` Include the workflow file itself in its own paths. If a filtered check is a required status check, add a no-op fallback workflow with the inverse `paths-ignore` so PRs that don't touch the service aren't blocked forever. ## Artifacts Upload build outputs when a later job or a human needs them: ```yaml - uses: actions/upload-artifact@v5 with: name: server-dist path: dist/ retention-days: 7 ``` Set `retention-days` deliberately (default 90 wastes storage). Pass files between jobs via artifacts, not by rebuilding. Test reports/coverage: upload with `if: always()` so failures still produce the report. ## Checklist for a new workflow - [ ] Triggers: `push` to main + `pull_request`, no double-trigger - [ ] `concurrency` with `cancel-in-progress: true` - [ ] `permissions: contents: read` at top; extras per-job only - [ ] Third-party actions SHA-pinned with version comment - [ ] setup-go / setup-node built-in caching, keyed off lockfile - [ ] Installs use lockfile-strict mode (`npm ci`, `pnpm install --frozen-lockfile`, `bun install --frozen-lockfile`) - [ ] No matrix unless multiple targets are truly supported - [ ] Secrets via environments; none in lint/test/build jobs - [ ] Monorepo: `paths` filters incl. the workflow file - [ ] Artifacts have `retention-days`; reports uploaded `if: always()` - [ ] Runtime versions read from the repo (`go.mod`, `.nvmrc`/`package.json engines`), not hardcoded twice