merge-mentor

Getting Started & Configuration

Merge Mentor can be configured using environment variables, command-line parameters, or a combination of both. Command-line parameters always override environment variables.

Prerequisites

Node.js 22+
Supported Platforms: Windows, macOS, and Linux
AI Provider Prerequisites:
- Copilot SDK (copilot-sdk): Requires a valid Copilot token set via MM_COPILOT_TOKEN or --copilot-token.
- OpenCode SDK (opencode-sdk): Follow the official OpenCode installation instructions at https://opencode.dev.
Platform Access: Personal access token for GitHub or Azure DevOps.

Environment Variables

All environment variables use the MM_ prefix to avoid conflicts with other applications.

The default platform is Azure DevOps. Set MM_PLATFORM=github (or pass --platform github) to default to GitHub instead.

GitHub Platform Configuration

export MM_PLATFORM=github
export MM_GITHUB_TOKEN=your_personal_access_token
export MM_GITHUB_REPO_OWNER=username_or_org
export MM_GITHUB_REPO_NAME=repository_name

Azure DevOps Platform Configuration

export MM_PLATFORM=azure
export MM_AZURE_TOKEN=your_pat
export MM_AZURE_ORG=organization_name
export MM_AZURE_PROJECT=project_name
export MM_AZURE_REPO=repository_name

Token Permissions

GitHub Token (set via MM_GITHUB_TOKEN or --github-token):
- repo scope (full control of private repositories)
- Or public_repo for public repositories only
- Note: If running inside a GitHub Actions workflow, you can use the built-in GITHUB_TOKEN by setting permissions: pull-requests: write.
Azure DevOps PAT (set via MM_AZURE_TOKEN or --azure-token):
- Code: Read & Write
- Pull Request Threads: Read & Write

AI Provider Configuration

Default Provider: GitHub Copilot SDK (copilot-sdk)

# Select AI provider (copilot-sdk, opencode-sdk).
export MM_AI_PROVIDER=copilot-sdk

# Shared AI timeout (default: 3600000 ms / 1 hour)
export MM_AI_TIMEOUT=3600000

# AI Model Name (optional, defaults depend on active provider)
export MM_AI_MODEL=gpt-6-sol

Available Models

Configure the active provider model via MM_AI_MODEL or --ai-model. Example:

gpt-6-sol

Check provider documentation for all supported models.

Planning Model

The plan command uses a higher-tier planning model. By default it uses the active MM_AI_MODEL; override it per invocation with --plan-model <model>.

merge-mentor plan --id 123 --base main --plan-model gpt-6-sol

Bring Your Own Key (BYOK) Examples

You can use MM_AI_BASE_URL and MM_AI_API_KEY to configure custom OpenAI-compatible endpoints:

1. Locally-Hosted Model (e.g. Ollama or vLLM)

export MM_AI_PROVIDER=copilot-sdk
export MM_AI_BASE_URL=http://localhost:11434/v1/
export MM_AI_API_KEY=ollama             # Some clients require a non-empty key
export MM_AI_MODEL=gpt-6-sol             # Your local model name

2. Azure OpenAI

export MM_AI_PROVIDER=copilot-sdk
export MM_AI_BASE_URL=https://your-resource-name.openai.azure.com/openai/deployments/your-deployment-name/
export MM_AI_API_KEY=your_azure_api_key
export MM_AI_MODEL=gpt-6-sol            # Your deployed model name

BYOK settings are currently supported by copilot-sdk only. When opencode-sdk is selected, supplying MM_AI_BASE_URL or MM_AI_API_KEY fails fast; configure OpenCode providers through its own configuration instead.

Optional Settings

# Review profile strategy (fast, deep, or multi-agent)
export MM_REVIEW_STRATEGY=fast

# Reasoning effort level (low, medium, high, xhigh)
export MM_REASONING=high

# Stream incremental AI output when the provider supports it (true/false)
export MM_STREAMING_ENABLED=true

# Pin Copilot sessions to the long-context tier (true/false)
export MM_LONG_CONTEXT=true

# Enable experimental structured output via Copilot SDK tool calls (true/false)
export MM_EXPERIMENTAL_TOOLS=true

# Verify PR changes against linked Product Backlog Items or Issues (true/false)
export MM_VERIFY_PBI=true

# Git backend for cloning (cli or isomorphic)
export MM_GIT_BACKEND=cli

# Base path for temporary files (cache, logs, reports, etc.)
export MM_TEMP_PATH=./.mergementor

# Logging
export LOG_LEVEL=info  # debug, info, warn, error

# Audit logging (enabled by default for security/compliance)
export AUDIT_LOGGING_ENABLED=true

# Streaming output display
export MM_STREAMING_ENABLED=true  # Enable/disable streaming output
export MM_STREAMING_LINES=9       # Number of lines to stream (1-20)

Logging and Temporary Directories

By default, Merge Mentor stores temporary files in ./.mergementor relative to the current working directory. You can customize this location using the MM_TEMP_PATH environment variable or --temp-path CLI flag.

Important Directories

logs/: Timestamped log files for debugging and audit trails (.mergementor/logs/).
reports/: Markdown review reports from dry-run mode (.mergementor/reports/).
cache/: Incremental review cache to track already-reviewed files (.mergementor/cache/).
runs/: Web UI review runs, each with a manifest, an append-only event log, and a final summary (.mergementor/runs/<runId>/). These let the web UI resume or replay a review after a page refresh or server restart.

Web UI Run Retention

Completed web UI runs are pruned so the runs/ directory does not grow without bound. Set MM_RUN_RETENTION_MS to control how long a run is kept (default 604800000, i.e. 7 days). A run is pruned once it is older than this or falls outside the newest 100 runs; runs still in progress are never pruned.

Audit Logging

Audit logging is enabled by default for security and compliance tracking. All critical actions are logged with structured data including PR Operations, Comment Actions, LLM executions, and Review Lifecycles.

Logs are written to timestamped log files (.mergementor/logs/merge-mentor_YYYY-MM-DD_HH-mm-ss.log) with a dedicated audit field for easy filtering and analysis.

This site is open source. Improve this page.