Environment Variables

Self-Hosted Variables

These variables are configured in your .env file or passed directly to docker compose.

Self-hosted deployments use a .env file alongside docker-compose.yml. See the install guide for the recommended setup path.

Core

Variable	Required	Default	Description
`GITHUB_APP_ID`	Yes	—	Numeric GitHub App ID from your app settings page
`GITHUB_PRIVATE_KEY`	Yes	—	PEM-encoded RSA private key generated for the GitHub App
`GITHUB_WEBHOOK_SECRET`	Yes	—	HMAC secret used to validate incoming webhook payloads
`DATABASE_URL`	Yes	—	Postgres connection string, e.g. `postgresql://user:pass@postgres:5432/mergewatch`
`LLM_PROVIDER`	Yes	`anthropic`	LLM backend to use: `anthropic`, `litellm`, `bedrock`, or `ollama`
`LLM_MODEL`	No	—	Override the default model for the selected provider
`PORT`	No	`3000`	Port the MergeWatch server listens on inside the container
`GITHUB_APP_SLUG`	No	—	GitHub App slug, used to generate the installation link
`GITHUB_PRIVATE_KEY_FILE`	No	—	Path to PEM file — alternative to inline `GITHUB_PRIVATE_KEY`
`DASHBOARD_BASE_URL`	No	—	Public base URL of the dashboard (e.g., `https://dashboard.example.com`). Read by the server to generate deep links in PR comments.
`DASHBOARD_URL`	No	`http://localhost:3001`	Consumed by `docker-compose.yml` to set `NEXTAUTH_URL` on the dashboard container. Set when serving the dashboard on a public domain.
`LLM_MODEL_INPUT_PRICE_PER_1M`	No	—	USD per 1M input tokens for whatever `LLM_MODEL` is set to. Lets a self-hosted deployment show real per-PR and dashboard cost instead of “unpriced” — including for an opaque Bedrock inference-profile ARN. Must be set together with the output price.
`LLM_MODEL_OUTPUT_PRICE_PER_1M`	No	—	USD per 1M output tokens for `LLM_MODEL`. Both prices must be finite and non-negative, and both must be present — if either is missing or invalid, neither is applied. `0` / `0` is valid and records a real $0 for a local model.
`REVIEW_CONCURRENCY`	No	`3`	How many reviews the background worker processes at once. The worker drains a durable Postgres job queue, so a burst of pull requests becomes a paced stream instead of N simultaneous LLM calls against your provider’s rate limit. Raise it if your provider quota allows more throughput; lower it to be gentler. Non-numeric or non-positive values fall back to the default.
`INSIGHTS_ROLLUP_INTERVAL_MINUTES`	No	`60`	How often the insights rollup runs, in minutes. Raise it to reduce database load. Unset, non-numeric, or non-positive values fall back to the hourly default.

Provider-specific: Anthropic

Variable	Required	Default	Description
`ANTHROPIC_API_KEY`	If `LLM_PROVIDER=anthropic`	—	API key from console.anthropic.com

Provider-specific: LiteLLM

Variable	Required	Default	Description
`LITELLM_BASE_URL`	If `LLM_PROVIDER=litellm`	—	Base URL of your LiteLLM proxy, e.g. `http://litellm:4000`
`LITELLM_API_KEY`	No	—	Optional API key if your LiteLLM proxy requires authentication

Provider-specific: Ollama

Variable	Required	Default	Description
`OLLAMA_BASE_URL`	If `LLM_PROVIDER=ollama`	`http://localhost:11434`	Base URL of the Ollama server

Provider-specific: AWS Bedrock

Variable	Required	Default	Description
`AWS_REGION`	If `LLM_PROVIDER=bedrock`	—	AWS region for Bedrock API calls
`AWS_ACCESS_KEY_ID`	If `LLM_PROVIDER=bedrock`	—	AWS access key (or use an instance profile instead)
`AWS_SECRET_ACCESS_KEY`	If `LLM_PROVIDER=bedrock`	—	AWS secret key (or use an instance profile instead)

If you run MergeWatch on an EC2 instance or ECS task with an IAM instance profile or task role that has Bedrock permissions, you can omit AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. The AWS SDK will pick up credentials automatically.

Dashboard (Self-Hosted)

The dashboard container runs on port 3001 (the Express server uses 3000). These variables are set on the dashboard service in docker-compose.yml.

Variable	Required	Default	Description
`GITHUB_CLIENT_ID`	Yes	—	OAuth client ID from your GitHub App’s OAuth Credentials section
`GITHUB_CLIENT_SECRET`	Yes	—	OAuth client secret from your GitHub App
`NEXTAUTH_SECRET`	Yes	—	Random secret for session signing (generate with `openssl rand -base64 32`)
`NEXTAUTH_URL`	No	`http://localhost:3001`	Public URL the dashboard is served from. Docker Compose sets this from `DASHBOARD_URL`.
`DEPLOYMENT_MODE`	No	`self-hosted`	Set to `saas` to enable the billing UI.

SaaS Lambda Variables

These variables are used internally by the MergeWatch SaaS infrastructure. They are documented here for reference only and are not user-configurable.

The SaaS deployment runs on AWS Lambda and does not use LLM_PROVIDER, DATABASE_URL, or any of the self-hosted provider variables. Bedrock access is handled via the Lambda execution role.

Core Lambda

Variable	Description
`DEPLOYMENT_MODE`	Deployment mode — `saas` or `self-hosted`. Gates billing and SaaS-only code paths.
`INSTALLATIONS_TABLE`	DynamoDB table name for GitHub App installations
`REVIEWS_TABLE`	DynamoDB table name for review records
`REVIEW_AGENT_FUNCTION_NAME`	Name of the ReviewAgent Lambda (the WebhookHandler invokes it async)
`DEFAULT_BEDROCK_MODEL_ID`	Bedrock model used by the review agents (SAM parameter)
`DEFAULT_LIGHT_MODEL_ID`	Bedrock model used for low-complexity tasks such as summary generation. Defaults to `us.anthropic.claude-haiku-4-5-20251001-v1:0` when unset. Overridden per-repo by `lightModel` in `.mergewatch.yml`.

Billing Lambda (Stripe)

Configured when DeploymentMode=saas. Credentials are pulled from SSM at deploy time — see BILLING_SETUP.md for details.

Variable	Description
`STRIPE_SECRET_KEY`	Stripe API secret key. Read from SSM (`/mergewatch/{stage}/stripe-secret-key`), with an environment-variable override honoured for local development and tests.
`STRIPE_WEBHOOK_SECRET`	Stripe webhook signing secret. Read from SSM only (`/mergewatch/{stage}/stripe-webhook-secret`) — unlike the two below, there is no environment-variable override, so setting this in the environment has no effect.
`BILLING_API_SECRET`	Shared secret for dashboard → BillingHandler auth (from `/mergewatch/{stage}/billing-api-secret`)

Dashboard (Amplify) env vars for SaaS mode

Variable	Description
`DEPLOYMENT_MODE`	`saas` — toggles the billing UI in the dashboard
`BILLING_API_URL`	`BillingUrl` from SAM stack outputs (e.g., `https://…/dev/billing`)
`BILLING_API_SECRET`	Same value as above, read from SSM and set in Amplify

Overview

Self-Hosting

LLM Providers

Platform Guides

Configuration

GitHub App

Deployment

Dashboard

Managed SaaS

Reference

Environment Variables

Self-Hosted Variables

Core

Provider-specific: Anthropic

Provider-specific: LiteLLM

Provider-specific: Ollama

Provider-specific: AWS Bedrock

Dashboard (Self-Hosted)

SaaS Lambda Variables

Core Lambda

Billing Lambda (Stripe)

Dashboard (Amplify) env vars for SaaS mode

Next steps

Install Guide

Commands Reference

​Self-Hosted Variables

​Core

​Provider-specific: Anthropic

​Provider-specific: LiteLLM

​Provider-specific: Ollama

​Provider-specific: AWS Bedrock

​Dashboard (Self-Hosted)

​SaaS Lambda Variables

​Core Lambda

​Billing Lambda (Stripe)

​Dashboard (Amplify) env vars for SaaS mode

​Next steps

Install Guide

Commands Reference

Self-Hosted Variables

Core

Provider-specific: Anthropic

Provider-specific: LiteLLM

Provider-specific: Ollama

Provider-specific: AWS Bedrock

Dashboard (Self-Hosted)

SaaS Lambda Variables

Core Lambda

Billing Lambda (Stripe)

Dashboard (Amplify) env vars for SaaS mode

Next steps