Contributing
Local development
Run the QA environment with pnpm dev, and check your work with pnpm gate before you commit.
This page is for people changing CirCI's own code: how to start the development environment and what to run before you commit.
Set up
Section titled “Set up”You need Node 26 (nvm install && nvm use reads .nvmrc), pnpm 12 and, for pnpm dev, Docker.
-
Install the dependencies.
pnpm install -
Install Chromium once. Component tests run in headless Chromium.
pnpm exec playwright install chromium -
Start the QA environment.
pnpm dev
pnpm dev
Section titled “pnpm dev”pnpm dev is the local QA environment, and the dashboard on http://localhost:5173 is what you open. It starts:
| Part | What runs | Where |
|---|---|---|
| Postgres and Mailpit | Docker containers (Compose project circi-dev) |
Mailpit catches every email the server sends |
| The server and worker | circi all from source under node --watch, so a change restarts it |
Port 3000 |
| The dashboard | Vite with hot reload. It proxies every server path to the server | Port 5173 (PUBLIC_URL) |
| A webhook receiver | A tiny server that answers every webhook delivery and logs it | Port 4747 (CIRCI_DEV_HOOKS_PORT) |
On the first run it seeds owner@example.com and member@example.com (password circi-dev-password), the workspace acme, the project web-app and builds in different review statuses, so every screen has something to show.
The seeded projects have webhooks that deliver to the receiver. It answers 204, and logs each delivery as a [hooks] line with its event, its delivery ID and whether the signature checked out. The signature is checked only for the webhooks the seed created, whose secrets it saved for the receiver; a webhook you add in the dashboard logs "signature not checked" rather than an invalid one. One seeded webhook points at /fail/always, which answers 500, so failed deliveries and retries show in the dashboard's webhook list. Bodies over 1 MiB get 413. The failing webhook exists in a fresh seed only: an existing dev database doesn't get it until pnpm dev:reset.
pnpm dev # Ctrl+C stops it and keeps the datapnpm dev:reset # delete the dev database and files; the next pnpm dev seeds again (a fresh seed)To run the server from source against your own Postgres:
DATABASE_URL=postgres://… BETTER_AUTH_SECRET=$(openssl rand -base64 32) STORAGE_PATH=./data pnpm circi allBefore committing: pnpm gate
Section titled “Before committing: pnpm gate”Run the formatter, then the gate.
pnpm format # oxfmtpnpm gate # Turborepo: format check, lint, typecheck, tests and buildpnpm gate runs these in parallel where they're independent, each cached by its inputs, so a second run on an unchanged tree is instant:
| Task | What it checks |
|---|---|
| Format check | oxfmt |
| Lint | oxlint, type-aware, plus the layer rules from Repo layout |
| Typecheck | tsc with noEmit |
| Tests | The Node, UI and web browser projects (see Tests) |
| Build | tsdown for @circi/ui, @circi/cli, @circi/vitest and the server bundle, then Vite for the dashboard |
pnpm gate:full adds the two end-to-end groups, which need Docker and Chromium.
tsc only type-checks. Packages other than the four above have no build: their exports point at src/*.ts, which Node, Vitest, Vite, tsc and tsdown all read directly.
Database changes
Section titled “Database changes”Edit the table files in packages/db/src/schema/, then run pnpm db:generate, which writes a SQL migration to packages/db/migrations/. Commit both. After changing better-auth's plugins run pnpm db:auth-schema, then pnpm db:generate.
Performance suite
Section titled “Performance suite”pnpm perf runs the k6 suite against a fresh stack. pnpm perf:down tears it down and pnpm perf:bench runs the diff microbenchmark. Results go to perf/results.