CI, CD and Docker

Workflows (.github/workflows/)

npm authentication is trusted publishing (OIDC), not a token: the npmjs.com package has a trusted publisher for GitHub Actions (luigi-dv/react-ts-vite, workflow release.yml, environment release). The release job needs id-token: write; npm ≥ 11.5.1 exchanges the OIDC token itself (an existing token is overridden, failures fall back silently to the configured token, so a missing trusted publisher shows up as a 401/404 on publish). Provenance is generated automatically for public packages. Never add an npm_token secret unless you deliberately switch back to token auth (NODE_AUTH_TOKEN on the publish step).

Staged publishing (PUBLISH_MODE: staged, the default): CI runs npm stage publish, which every trusted publisher may do; the version is stored but not public, occupies its semver slot (re-running the pipeline detects the conflict and reports the version as staged) and keeps the dist-tag given at stage time. A maintainer approves with npm stage approve <stage-id> (2FA, write access; trusted-publisher tokens cannot run npm stage subcommands other than stage publish). direct mode runs npm publish and needs "Allow npm publish" on the trusted publisher.

Conventions: pin actions by major (actions/checkout@v5, actions/setup-node@v5), use node-version-file: .nvmrc, cache npm, keep permissions minimal and explicit, prefer one npm run check over many separate steps so local and CI gates are identical.

Debugging a red CI

1. Reproduce locally with the same command (npm run check, npm run build). Node version differences? Use nvm use (.nvmrc = 24).
2. Format failures → npm run format. Lint → npm run lint:fix then fix the rest by hand. Architecture → skill project-architecture. Agent sync → npm run agent:sync and commit.
3. Architecture smoke job failing: run the same loop locally (see the job's run: block). It catches templates or code that only work in one architecture.
4. Never fix CI by deleting a check, skipping a test or adding continue-on-error.

Deploying the app

The build is static (dist/). Any static host works: Vercel/Netlify (framework preset Vite, output dist), GitHub Pages (actions/upload-pages-artifact on dist), S3/CloudFront, or the Docker production image below. Set base in vite.config.ts when the app is served from a sub-path. Runtime config goes through VITE_* environment variables (import.meta.env.VITE_API_URL); never ship secrets to the client bundle.

Hosts that create GitHub deployments (Vercel, Netlify, Render…) trigger the deployment_status event, which is how the Claude insights workflow runs after each successful deployment.

Docker

# development — Vite dev server with hot reload (source mounted as a volume)
docker compose -f docker/development/docker-compose.yml up --build

# production — multi-stage build, nginx serving dist/ on :3000 with SPA fallback
docker compose -f docker/production/docker-compose.yml up --build

docker/production/nginx.conf sets immutable caching for /assets/, no-cache for index.html, gzip and basic security headers. Adjust add_header Content-Security-Policy when you know your origins.

Adding a workflow

Copy the structure of build.yml, keep permissions explicit, use npm ci, run npm run check before anything that deploys, and document the new workflow here and in docs/deployment-insights.md or README.md.