Configuration

Environment variables, provider selection, and operational settings.

Environment Variables

MergeWhy uses environment variables for all configuration. Below is the complete reference grouped by category.

Core (Required)

.env

# PostgreSQL connection (pooled)
DATABASE_URL=postgresql://user:pass@host:5432/mergewhy

# PostgreSQL connection (direct, for migrations)
DIRECT_URL=postgresql://user:pass@host:5432/mergewhy

# Application base URL
NEXT_PUBLIC_APP_URL=https://mergewhy.example.com

Deployment Mode

.env

DEPLOYMENT_MODE=self-hosted    # "saas" (default) | "self-hosted"
AUTH_PROVIDER=oidc             # "clerk" | "oidc"
STORAGE_PROVIDER=s3            # "database" | "s3"
LLM_PROVIDER=anthropic         # "anthropic" | "openai" | "ollama" | "none"

OIDC Authentication

.env

OIDC_ISSUER_URL=https://login.example.com/realms/main
OIDC_CLIENT_ID=mergewhy
OIDC_CLIENT_SECRET=your-client-secret
OIDC_SCOPES="openid profile email"
OIDC_DEFAULT_ORG=default-org-id
OIDC_OWNER_ROLES="admin,super-admin"
OIDC_ADMIN_ROLES="manager"
NEXTAUTH_SECRET=random-32-char-secret
NEXTAUTH_URL=https://mergewhy.example.com

GitHub Integration

.env

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
GITHUB_CLIENT_ID=Iv1.abc123
GITHUB_CLIENT_SECRET=secret
GITHUB_WEBHOOK_SECRET=webhook-secret
NEXT_PUBLIC_GITHUB_APP_SLUG=mergewhy

S3 Storage

.env

S3_BUCKET=mergewhy-evidence
S3_REGION=us-east-1
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com  # or MinIO URL
S3_ACCESS_KEY_ID=AKIA...
S3_SECRET_ACCESS_KEY=...
S3_FORCE_PATH_STYLE=false   # set to "true" for MinIO

LLM Providers

AI analysis is optional. If no LLM API key is configured, MergeWhy falls back to rule-based analysis that checks description length, keyword presence, and ticket references.

.env

# Anthropic Claude (recommended)
ANTHROPIC_API_KEY=sk-ant-...

# OpenAI (alternative)
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1  # or Azure OpenAI URL

# Ollama (local, air-gapped)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3

Optional Services

.env

# Jira integration
JIRA_CLIENT_ID=your-jira-client-id
JIRA_CLIENT_SECRET=your-jira-secret

# Slack integration
SLACK_CLIENT_ID=your-slack-client-id
SLACK_CLIENT_SECRET=your-slack-secret

# Email (Resend)
RESEND_API_KEY=re_...
EMAIL_FROM=noreply@mergewhy.example.com

# Cron job protection
CRON_SECRET=random-secret-for-cron-endpoints

Self-Hosted Deployment OIDC Authentication Setup