ApprovalOps

A GitHub App for turning pull-request activity into review evidence, readiness signals, and actionable approval summaries.

Status: the hosted service has been discontinued. This repository is an engineering portfolio of the implementation, with historical commits retained after privacy cleanup. There is no hosted demo or active product roadmap.

What it does

• Ingests GitHub webhooks and processes pull-request changes through background jobs.
• Builds review evidence from changed files, reviews, ownership, checks, and observation windows.
• Computes readiness and risk signals, with policy gates and repository calibration.
• Publishes GitHub checks and evidence comments, and exposes repository dashboards.
• Evaluates behavior through replay, synthetic scenarios, and in-memory GitHub provider emulators.

Architecture

flowchart LR
  GitHub[GitHub webhooks] --> API[Fastify API]
  API --> DB[(PostgreSQL + pgvector)]
  API --> Queue[Redis / BullMQ]
  Queue --> Worker[TypeScript workers]
  Worker --> Engine[Approval evidence and scoring]
  Engine --> DB
  Worker --> Publication[GitHub checks and comments]
  Web[Next.js dashboard] --> API
  Eval[Replay and evaluation API] --> DB
  Eval --> Queue

Loading

The monorepo uses TypeScript, Next.js App Router, React, Fastify, Drizzle, PostgreSQL, pgvector, Redis, BullMQ, pnpm workspaces, Turbo, and Vitest.

Location	Responsibility
approvalops/apps/web	Repository dashboards and evaluation UI
platform/apps/api	Webhooks, access control, repository APIs, and operational routes
platform/apps/worker	Queue registration and runtime composition
approvalops/packages/approval-engine	Evidence, scoring, policy gates, and calibration
approvalops/packages/worker-runtime	Backfill, observation, recomputation, and publication jobs
packages/github	GitHub transport, caching, publication, and emulators
packages/db	Schema, migrations, and persistence helpers
approvalops/apps/eval-api	Replay and evaluation control plane

Suggested code tour

1. Webhook verification and API composition.
2. Worker registration and pull-request event processing.
3. Readiness scoring tests.
4. Publication runtime and provider emulator.

Local setup

Use Node.js ^22.13.0 or >=24.0.0, pnpm 11.0.9, and Docker for the local datastores.

pnpm install --frozen-lockfile
cat .env.example .env.approvalops.example > .env
docker compose -f infra/compose/docker-compose.yml up -d postgres redis
pnpm db:migrate
pnpm db:seed

The example configuration contains placeholders. To run the application against GitHub, configure your own GitHub App, OAuth credentials, webhook secret, and private key in the ignored .env file. Update the local URLs for your callback/webhook setup, then run pnpm dev and pnpm dev:worker in separate terminals. AI output can use the stub provider in the example configuration; real providers require your own configuration.

Local datastore credentials are development examples. Production deployment configuration and historical credentials are deliberately absent.

Validation

After installing dependencies and preparing the example .env, run:

pnpm ci:approvalops:static
pnpm ci:shared
pnpm ci:approvalops:test
pnpm test:e2e
pnpm runtime:scenario:suite:ci

The E2E command checks the harness; the scenario CI command performs a dry run. They do not demonstrate a live GitHub deployment. Datastore integration tests are separate (pnpm test:integration -- --no-env-local) and require Docker or dedicated test database/Redis URLs.

A GitHub Actions template is available for future activation. The published repository currently uses local validation.

About the published history

This is an independent, sanitized repository. Its 223 historical commits retain their authors, dates, order, and parent relationships; private email addresses use the author's GitHub noreply address. Commit hashes changed during cleanup. Some commits are empty because their content was private documentation or excluded product work.

Credentials, private keys, local environment files, internal documents, deployment automation, and sibling-product code were removed from history. Historical versions of shared files that mixed product responsibilities were omitted; their reviewed ApprovalOps-only versions were added in the portfolio preparation commit. Sensitive or sibling-product commit messages were redacted. Old branches, tags, pull requests, releases, and Actions records were not migrated.

See design, project status, and remaining work.