Quality

CI/CD

The jobs that run on a pull request, when each one runs, how to add one, and what a merge deploys.

The jobs

Every pull request runs .github/workflows/ci.yml on GitHub Actions:

JobWhat it checks
Lint, deps, formatoxlint, syncpack, Prettier, the client env allowlist, and generated files against their sources
Backend testsThe full Vitest suite
Storybook testsEvery play test in Chromium
SemgrepThe rule tests, then the scan
ZAP scan and signed-in CSPThe web app's CSP, signed out and signed in, then ZAP against a running stack
Accessibility and CSPThe accessibility sweep, and the CSP on every static page
BuildsThe web app, marketing site, blog, and docs, then the secrets scan of their output

A draft runs nothing. Detect changes skips on a draft, and every other job needs it. Marking the pull request ready runs everything.

When a job runs

The first job, Detect changes, lists the pull request's files and decides which checks they affect. Every other job reads its list and skips when it isn't there.

Each check has a pattern in the paths map at the top of ci.yml. A pattern includes the check's own files and every workspace it imports, so a shared-ui change reruns the web-app build. Root files — package.json, yarn.lock, the workflows — run everything. Markdown only counts for formatting.

A manual run from the Actions tab runs every check.

Add a check

  1. Add an area to the paths map in the Detect changes job, with a pattern for every file it reads.
  2. Add a step to an existing job, or a new job with needs: changes and an if: on the area.
  3. Use ./.github/actions/setup for Node and dependencies. Pass playwright: "true" if it needs Chromium.

Put a new job in its own job when its failure means something different from its neighbors'. An accessibility failure isn't a broken build, so it has its own job.

Artifacts

Each build is uploaded for three days as <app>-pr-<number>, and older uploads from the same pull request are deleted. The accessibility and ZAP jobs upload their reports as a11y-report and zap-report.

Required checks

The main ruleset requires a pull request, and these checks to pass: Lint, deps, format; Storybook tests; Builds; Backend tests; and Infra.

Deploys

.github/workflows/deploy.yml runs after a merge to main that touches anything production runs: the backend, the four sites, shared-ui, infra, dependencies, or the workflow itself. It runs as one job on an ARM runner, in the GitHub production environment, which only accepts runs from main:

  1. Typecheck and test infra/.
  2. Build the web app, marketing site, blog, and docs with production's URLs. The blog reads its posts from the live backend.
  3. Build the backend image and push it to ECR, tagged with the commit.
  4. Deploy DNS, the backup vault, and production with CDK.
  5. Run migrations with the new image, then release it.
  6. Deploy the edge: the certificate and the CloudFront distributions.
  7. Upload the sites and invalidate each distribution.
  8. Smoke-test the API's /health and every site.

Each step signs in to its AWS account with a short-lived OIDC token. There are no AWS keys in GitHub.

  • Run it by hand with "Run workflow" on the Deploy workflow.
  • Roll back by rerunning an earlier successful Deploy run. It rebuilds that commit's image and deploys that commit's infrastructure. Migrations don't run backward, so a rollback across a schema change needs a forward fix instead.
  • Not deployed by CI: the AWS organization, cost monitoring, and CI's own roles. They're deployed by hand, so CI can't change its own access.

infra/README.md has the stacks, the first-time setup, and the cost tiers.

Not built

  • Desktop builds. A Tauri build needs Rust and system libraries, and would be its own workflow.
  • Staging. Production is the only deployed environment.
  • CI/CD — what runs, why only what changed, and why merging deploys.
  • GitHub Actions — how the workflow is shaped.
  • Testing — running the tests yourself.