Verge is an evidence-based CI/CD control plane.
Instead of treating CI as a fixed list of workflows that only end in pass or fail, Verge records structured evidence about repository health over time. It decides what to run, what can be reused, what can be resumed, and what parts of a repository are still stale or unknown.
The current MVP runs Verge on the Verge repository itself.
The repository currently includes:
- a root
verge.config.tsthat defines the Verge repo's own steps - a workspace
vergeCLI for API, worker, sync, and process discovery commands - a Fastify API in
apps/api - a React + Vite dashboard in
apps/web - a long-running worker in
apps/worker - shared contracts, planning logic, and persistence packages in
packages/* - Postgres-backed persistence via Kysely
- local filesystem-backed artifact and checkpoint storage
- GitHub webhook ingestion
- manual run creation
- process reuse
- checkpoint-based resume for cooperative steps
- GitHub Actions CI that validates the repo and runs a self-hosted smoke test
The main runtime shape is:
run -> step -> process -> observation
In plain terms:
- a
runis one commit-level, PR-level, or manual evaluation - a
stepis a major check inside a run, liketestorbuild - a
processis the smallest meaningful thing Verge tracks as its own result - an
observationis the recorded result
A process should not be an execution chunk or grouping convenience. It should be the real unit of evidence, such as one test, one lint target, one build target, or one document check.
apps/
api/
web/
worker/
packages/
contracts/
core/
db/
infra/
local/
scripts/
docs/
This repo is TypeScript-first and uses:
pnpmvitevitestoxlintoxfmt
The repo now also has a typed config and CLI boundary:
verge.config.tsas the repository contractpnpm exec verge ...as the operational entry point
- Node.js 22+
pnpm- PostgreSQL
You can use the included Compose file for local Postgres:
pnpm db:up
pnpm db:migrateBy default the local database URL is:
postgres://verge:verge@127.0.0.1:54329/verge
pnpm installpnpm devThis starts:
- the API on
http://127.0.0.1:8787 - the worker
- the Vite web app
pnpm exec verge sync
pnpm exec verge api
pnpm exec verge worker
pnpm lint
pnpm format:check
pnpm typecheck
pnpm test
pnpm build
pnpm docs:validate
pnpm test:integration
pnpm test:smokeVerge is intended to validate itself.
The self-hosted steps currently cover:
format-checklinttypechecktestbuilddocs:validate
The test step now materializes one process per individual Vitest test. The smoke test boots the API and worker, creates a manual run against this repo, executes the self-hosted steps, and verifies checkpoint-based resume on the test step.
GitHub Actions runs the following on pull requests and on main:
- formatting
- lint
- typecheck
- docs validation
- build
- unit tests
- DB-backed integration tests
- self-host smoke test
The workflow lives at .github/workflows/ci.yml.
The current MVP uses filesystem-backed artifact storage. Logs and checkpoints are written under .verge-artifacts by default.
This is a local-development and early-deployment choice. The storage model is intentionally abstract enough to move to object storage later.
The clean deployment shape for the current MVP is:
- one web service for
apps/api - one background worker for
apps/worker - one static site for
apps/web - one Postgres instance
- one persistent storage location for artifacts and checkpoints
The repo also includes a single-host Docker Compose deployment path with Caddy, Postgres, API, worker, and the built web UI:
Design and planning docs live in docs/:
- 2026-04-12-verge-ci-cd-control-plane.md
- 2026-04-12-verge-basic-objects.md
- 2026-04-12-verge-mvp-implementation-plan.md
- 2026-04-13-verge-cli-and-config-architecture.md
- 2026-04-13-local-ngrok-setup.md
- 2026-04-13-single-host-docker-compose-deployment.md
This is an MVP control plane, not a finished platform. The important thing it proves today is the full loop:
event in -> plan -> run -> record evidence -> query repository health