Getting started

ChangeGraph runs as a Next.js app. Deterministic scoring always runs. Investigation needs a configured LLM provider and fails closed as not_configured.

Where the running app reads data

The app server reads the in-memory ingest store: fixture tenant rows in src/lib/db/seed-data.ts, and the process-local memory store for webhooks and API routes. pnpm db:push and pnpm seed write the Postgres schema when DATABASE_URL is set. Request paths do not read that database.

Prerequisites

Node.js 20+
pnpm 12+ (repo pins packageManager)
Docker (for Postgres)

Install

From the repository root:

pnpm install
cp .env.example .env.local

Edit .env.local as needed. Empty GitHub / Sentry / Vercel keys are fine for fixtures. Set at least one LLM provider key for investigation.

Environment variables (essentials)

Variable	Purpose
`DATABASE_URL`	Postgres for `pnpm db:push` / `pnpm seed` (`postgres://changegraph:changegraph@localhost:5432/changegraph` matches Compose). See Where the running app reads data
`NEXT_PUBLIC_APP_URL`	Product app origin used by the incident dashboard (local default `http://localhost:3000`)
`GITHUB_` / `SENTRY_` / `VERCEL_*`	Leave empty for mock/seed; set for real ingestion
`VERCEL_USE_MOCK`	Defaults to mock when token empty (`1`)
`VERCEL_GITHUB_OWNER` / `VERCEL_GITHUB_REPO`	Live Vercel → GitHub repo binding (required when not mock; never `DEMO_GITHUB_*`)
`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `XAI_API_KEY` / `GROQ_API_KEY` / `FIREWORKS_API_KEY`	ChangeGraph provider router (`src/lib/llm/providers.ts`) for the in-repo Mastra-compatible runtime. Required for explain / investigate; missing keys fail closed as `not_configured`
`HEADROOM_URL` / `HEADROOM_API_KEY`	Optional Headroom after pack; packer works without it
`CHANGEGRAPH_MCP_TOKEN`	Required when exposing MCP beyond localhost
`INVESTIGATION_AGENT_ENABLED`	On by default. Set `0` to disable “Run investigation”

Demo mapping vars (DEMO_TENANT_ID, DEMO_GITHUB_OWNER, …) align with pnpm seed. See root .env.example and docs/AUTH.md for the local auth stub.

Postgres via Docker Compose

docker compose up -d postgres
pnpm db:push
pnpm seed

pnpm seed loads a sample org, repo, deploys, PRs, Sentry data, and candidates for scenarios A–D into Postgres when DATABASE_URL is set. Without Postgres, seed prints an offline plan and exits 0. See Where the running app reads data.

Optional full stack: docker compose --profile app up.

Start the product app

pnpm dev

Open http://localhost:3000. / lands on Dashboard. Fixtures A–D are on that dashboard and under Incidents. See Where the running app reads data.

Verify with tests

pnpm lint && pnpm typecheck && pnpm test && pnpm test:e2e && pnpm replay

Command	What it covers
`pnpm test`	Unit tests (scoring A–D, seed plan, agent flags, …)
`pnpm test:e2e`	API-level Vitest against seed/mocks + incident routes (no Playwright, no live network)
`pnpm replay`	Top-1 / Top-3 evaluation harness for A–D
`pnpm replay A`	Scenario A detail (breaker must be Top-1)

Replay metrics: repo docs/REPLAY.md. Local auth: docs/AUTH.md. Full local testing (feature gates, smoke checklist, troubleshooting): repo docs/TESTING.md.

Docs site (this app)

pnpm --filter docs dev
# → http://localhost:3001

Production build: pnpm --filter docs build. Deploy notes: apps/docs/README.md in this repository.

Verify the install

Exact commands from the repository root:

pnpm install
docker compose up -d postgres   # if Docker is available
pnpm db:push                    # when DATABASE_URL is set
pnpm seed
pnpm lint && pnpm typecheck && pnpm test && pnpm test:e2e && pnpm replay
pnpm --filter docs build

Next steps

Connect GitHub / Sentry / Vercel
Investigate an incident
Local fixtures A–D
Local testing, feature gates, smoke checklist: repo docs/TESTING.md
Scoring & last-known-good
Tools reference · Open source tools · Architecture