Skip to main content
MergeWatch self-hosted runs as a Docker container with a PostgreSQL sidecar. The entire setup takes about 10 minutes.
Make sure you have completed the Prerequisites before continuing.

​
Installation

1

Clone the repository

git clone https://github.com/santthosh/mergewatch.ai.git
cd mergewatch.ai
2

Configure environment variables

cp .env.example .env
Edit .env and fill in the required variables:
# ── GitHub App (required) ──────────────────────────────────────────────
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# ── GitHub OAuth (required for dashboard) ──────────────────────────────
# Found under: GitHub App Settings → OAuth Credentials (same App, not a separate OAuth App)
GITHUB_CLIENT_ID=Iv23ab...
GITHUB_CLIENT_SECRET=your-oauth-client-secret

# ── Dashboard auth (required for dashboard) ────────────────────────────
# Generate with: openssl rand -base64 32
NEXTAUTH_SECRET=random-32-byte-secret

# ── LLM Provider (pick one — Anthropic is the default) ─────────────────
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-4-20250514

# Handled by docker-compose — no changes needed
# DATABASE_URL=postgres://postgres:postgres@db:5432/mergewatch
# PORT=3000
VariableRequiredDescription
GITHUB_APP_IDYesThe numeric ID of your GitHub App
GITHUB_PRIVATE_KEYYesRSA private key for authenticating as the GitHub App (or use GITHUB_PRIVATE_KEY_FILE to point to a .pem file)
GITHUB_WEBHOOK_SECRETYesHMAC secret for validating webhook payloads
GITHUB_CLIENT_IDYesOAuth client ID from your GitHub App (used by the dashboard for sign-in)
GITHUB_CLIENT_SECRETYesOAuth client secret from your GitHub App
NEXTAUTH_SECRETYesRandom 32-byte secret for signing dashboard sessions (generate with openssl rand -base64 32)
ANTHROPIC_API_KEYIf LLM_PROVIDER=anthropicAPI key from console.anthropic.com
LLM_PROVIDERNoDefault: anthropic. Options: anthropic, litellm, bedrock, ollama
LLM_MODELYes for anthropic / litellm / ollamaModel ID. For Anthropic, use a native model ID like claude-sonnet-4-20250514 — the built-in defaults are Bedrock inference profile IDs and only work for LLM_PROVIDER=bedrock.
DASHBOARD_URLNoPublic URL of the dashboard (e.g., https://dashboard.example.com). Used as the NEXTAUTH_URL for session callbacks. Defaults to http://localhost:3001.
DATABASE_URLNoSet automatically by docker-compose (Postgres sidecar)
PORTNoDefault: 3000
To use a different LLM provider, set LLM_PROVIDER and the provider-specific variables. See LLM Providers.
3

Start MergeWatch

docker compose up -d
This starts three containers:
  • mergewatch — the Express server on port 3000 (handles GitHub webhooks)
  • dashboard — the Next.js dashboard on port 3001 (browser UI)
  • db — PostgreSQL 16 database
Database migrations run automatically on first startup.
4

Verify the deployment

Check that the server is running:
docker compose logs mergewatch
Look for this line in the output:
Server listening on port 3000
If the server fails to start, check that your .env file has all required variables set correctly (GITHUB_APP_ID, GITHUB_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET, GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, NEXTAUTH_SECRET, and your LLM provider key). See Troubleshooting for common issues.
5

Register your webhook URL

MergeWatch listens for GitHub webhooks at /webhook on port 3000. Configure your GitHub App’s webhook URL to:
https://your-domain.com/webhook
Set the webhook URL in GitHub Settings > Developer settings > GitHub Apps > Your App > Webhook URL.
Running locally? Use ngrok or Cloudflare Tunnel to expose port 3000 to the internet so GitHub can deliver webhooks.
ngrok http 3000
Use the generated https://...ngrok-free.app/webhook URL as your webhook URL.
6

Install the GitHub App on your repositories

  1. Go to GitHub Settings > Developer settings > GitHub Apps
  2. Find your MergeWatch app and click Install App
  3. Choose All repositories or select specific ones
  4. Click Install
Start with a single test repository. You can add more repos at any time from GitHub Settings > Applications > MergeWatch > Configure.
For detailed guidance, see Organization install or Personal install.

​
Your first pull request

Open a pull request against any installed repository. MergeWatch picks it up automatically. What to expect:
  • The Express server receives the pull_request.opened webhook event
  • The review pipeline fetches the diff and sends it to your LLM provider
  • A review comment appears on the pull request within 15—50 seconds (typical range; larger diffs and cold starts take longer)
The review includes:
  • A summary of the changes
  • File-by-file findings posted as inline review comments on changed lines
  • A 1–5 merge readiness score indicating how safe the PR is to merge

​
Next steps

LLM Providers

Switch from Anthropic to LiteLLM, Bedrock, or Ollama.

Platform Guides

Deploy to Google Cloud Run, AWS ECS, Azure, Fly.io, Railway, or bare metal.

Configure review behavior

Tune sensitivity, ignored paths, and review focus areas.

Upgrading

Keep MergeWatch up to date with the latest features and fixes.