.mergewatch.yml Reference

The .mergewatch.yml file controls how MergeWatch reviews pull requests in a repository. Place it at the root of your repository’s default branch (usually main).

Configuration priority

MergeWatch resolves configuration in the following order. Each layer overrides the one before it:

Built-in defaults

Hardcoded in the MergeWatch Lambda. These apply when no other configuration is present.

Installation-level settings (DynamoDB)

Set via the dashboard. Apply to all repositories in the installation.

Per-repo .mergewatch.yml

Checked into the repository. Overrides both built-in defaults and installation-level settings.

A .mergewatch.yml in the repository always wins. If you set maxFiles: 100 in the dashboard but maxFiles: 20 in the YAML file, the repo uses 20.

Validation

MergeWatch validates the .mergewatch.yml file on the first webhook it receives for the repository. If the file contains errors — invalid YAML, unknown properties, or type mismatches — MergeWatch posts the validation errors as a comment on the pull request so they are immediately visible to the author.

Full annotated example

.mergewatch.yml

version: 1

# Model used for all agents. Must be a valid Bedrock model ID.
model: us.anthropic.claude-sonnet-4-6

# Codebase awareness — enable agentic file fetching for cross-file context.
codebaseAwareness: true
maxFileRequestRounds: 1
maxContextKB: 256

# Agent configuration — toggle each built-in agent on or off.
agents:
  security: true
  bugs: true
  style: true
  errorHandling: true
  testCoverage: false
  commentAccuracy: true
  summary: true
  diagram: true

# Custom agents run alongside the built-in ones.
customAgents:
  - name: api-consistency
    prompt: "Check that all new API endpoints follow our REST conventions: plural resource names, consistent error response format, and proper HTTP status codes."
    severityDefault: warning
    enabled: true

# Review rules — control scope and trigger behavior.
rules:
  maxFiles: 50
  autoReview: true
  reviewOnMention: true
  skipDrafts: true
  ignoreLabels:
    - "skip-review"

# File patterns to exclude from the diff sent to agents.
excludePatterns:
  - "**/*.lock"
  - "**/package-lock.json"
  - "**/dist/**"
  - "**/node_modules/**"

# Force-include paths that would otherwise be PR-level skipped (e.g. docs-only PRs
# under a critical directory). Operates at the PR-skip layer, not the diff filter.
includePatterns:
  - "SECURITY.md"
  - "docs/policy/**"

# Agent-authored PR detection — flips reviews into strict mode and tracks iterations
# when commits look agent-generated.
agentReview:
  enabled: true
  strictChecks: true
  autoIterate: true
  maxIterations: 3
  passThreshold: noCritical          # noCritical | noFindings | scoreAtLeast4 | scoreAtLeast5
  detection:
    commitTrailers:
      - "Co-authored-by: Claude"
    branchPrefixes:
      - "claude/"
    labels:
      - "ai-generated"

# Minimum severity to report: info | warning | critical
minSeverity: info

# Minimum self-reported confidence (1-100) a finding needs to be reported.
# Lower to surface more speculative findings; raise for near-certain defects only.
minConfidence: 75

# Maximum findings posted per review.
maxFindings: 25

# UX configuration for review comment formatting.
ux:
  tone: collaborative       # collaborative | direct | advisory
  showWorkDone: true         # show the stats bar (files scanned, lines reviewed, agents ran)
  showSuppressedCount: true  # show how many findings were suppressed
  reviewerChecklist: true    # show a checklist derived from top findings
  allClearMessage: true      # show a special message when no findings
  commentHeader: ""          # custom Markdown header for the review comment

Property reference

Top-level properties

Property	Type	Default	Description
`version`	`number`	`1`	Schema version. Currently only `1` is supported.
`model`	`string`	(deployment default)	Bedrock model ID used for all agents. Any model available in your Bedrock account can be specified. When omitted, the deployment’s configured default is used — see Which model actually runs.
`lightModel`	`string`	`us.anthropic.claude-haiku-4-5-20251001-v1:0`	Lighter model used for low-complexity tasks such as summary generation.
`maxTokensPerAgent`	`number`	`4096`	Maximum output tokens per agent invocation. Increase for large PRs; decrease to reduce cost.
`minSeverity`	`string`	`info`	Minimum severity level to report. One of `info`, `warning`, `critical`. Findings below this threshold are suppressed.
`minConfidence`	`number`	`75`	Minimum self-reported confidence (`1`—`100`) a finding needs to be reported. Lower it (e.g. `50`) to surface the speculative tier MergeWatch normally withholds — useful when calibrating or when you suspect findings are being over-suppressed. Raise it to report only near-certain defects. Values outside `1`—`100` are ignored and the default applies.
`maxFindings`	`number`	`25`	Maximum number of findings posted per review. Prevents noisy reviews on large PRs.
`postSummaryOnClean`	`boolean`	`true`	When `true`, MergeWatch posts a summary comment even when no findings are detected. Set to `false` to stay silent on clean PRs. If an earlier review already posted a comment on the PR, it is still updated — a previously-flagged PR that comes back clean never keeps a stale review.
`codebaseAwareness`	`boolean`	`true`	Enable agentic file fetching for cross-file context. When `true`, agents can request additional files from the repository.
`maxFileRequestRounds`	`number`	`1`	Maximum rounds of file fetching per agent (1—2). Each round lets the agent request more files based on what it learned.
`maxContextKB`	`number`	`256`	Maximum total context size in KB for fetched files per agent. Prevents runaway context expansion.
`customStyleRules`	`string[]`	`[]`	Additional style rules applied to the style agent. Each entry is a rule string.
`conventions`	`string`	auto-discovered	Path to a Markdown file documenting repo-specific conventions. Injected into every agent’s prompt (16 KB cap). When unset, MergeWatch tries `AGENTS.md`, `CONVENTIONS.md`, and `.mergewatch/conventions.md` in that order. See Repository Conventions.
`excludePatterns`	`string[]`	See defaults	Canonical file-pattern field. Filters individual files out of the diff sent to agents. Uses glob syntax.
`includePatterns`	`string[]`	`[]`	Force PRs back into review when every changed file would otherwise match the built-in trivial patterns (lock files, docs, build artifacts). Operates at the PR-skip layer — useful for opting a critical-docs subdirectory or a top-level `SECURITY.md` back into review.
`agents`	`object`	See Agents	Boolean map of built-in agent names to enabled/disabled state.
`customAgents`	`CustomAgent[]`	`[]`	List of custom agent definitions. See Custom agents.
`rules`	`object`	See Rules	Review scope and trigger rules.
`ux`	`object`	See UX	UX configuration for review comment formatting.
`agentReview`	`object`	See Agent-authored PRs	Detection rules and strict-mode behavior for agent-authored pull requests.
`pricing`	`object`	provider defaults	Per-model price overrides for cost estimation. Map of model ID → `{ inputPer1M, outputPer1M }` in USD. Use this when a custom or self-hosted model is missing from MergeWatch’s built-in price table.

Agents

The agents object is a boolean map that toggles each of the eight built-in review agents on or off. Set an agent to false to disable it entirely.

agents:
  security: true
  bugs: true
  style: false        # disable style agent
  diagram: false      # disable diagram agent

You do not need to list all agents. Omitted agents default to true (enabled). To disable a single agent, include only that agent with false.

To define entirely new agents with custom prompts, use the customAgents array. See Custom agents below.

Built-in agents:

Agent	Default	Purpose
`security`	Enabled	OWASP Top 10, secrets detection, injection flaws, unsafe deserialization
`bugs`	Enabled	Logic errors, off-by-one, null dereferences, race conditions
`style`	Enabled	Code style, naming conventions, project-specific patterns
`errorHandling`	Enabled	Empty catch blocks, swallowed errors, unhandled promise rejections
`testCoverage`	Enabled	Missing tests for new public functions, untested edge cases
`commentAccuracy`	Enabled	Misleading or outdated code comments, incorrect JSDoc
`summary`	Enabled	High-level PR summary with the merge readiness score (uses the light model)
`diagram`	Enabled	Mermaid diagram of the changed control flow (uses the light model)

Custom agents

You can define custom agents using the customAgents array. Custom agents run in parallel alongside the built-in agents and follow the same output schema.

Property	Type	Default	Description
`name`	`string`	—	A unique identifier for the custom agent.
`prompt`	`string`	—	(Required) The system prompt for the agent. This defines what the agent looks for in the code.
`severityDefault`	`string`	`"warning"`	Default severity for findings from this agent. One of: `"info"`, `"warning"`, `"critical"`.
`enabled`	`boolean`	`true`	Set to `false` to disable the custom agent.

customAgents:
  - name: api-consistency
    prompt: "Check that all new API endpoints follow REST conventions: plural resource names, consistent error response format, and proper HTTP status codes."
    severityDefault: warning
    enabled: true

  - name: i18n-compliance
    prompt: "Flag any user-facing strings that are not wrapped in a translation function (t() or i18n()). All UI text must be translatable."
    severityDefault: info
    enabled: true

Rules

The rules object controls which files are reviewed and when reviews are triggered.

Property	Type	Default	Description
`maxFiles`	`number`	`50`	Maximum number of changed files to review. PRs exceeding this limit are skipped with a comment explaining why.
`autoReview`	`boolean`	`true`	When `true`, MergeWatch reviews every PR automatically on open and synchronize events. When `false`, MergeWatch leaves no trace on the PR at all — no reaction, no check run, no comment — and only a `@mergewatch` mention triggers a review. See Auto-review off.
`reviewOnMention`	`boolean`	`true`	When `true`, MergeWatch runs a review when mentioned in a PR comment (e.g., `@mergewatch review`). Works even if `autoReview` is `false`.
`skipDrafts`	`boolean`	`true`	Skip draft pull requests. Set to `false` to review drafts automatically.
`ignoreLabels`	`string[]`	`["skip-review"]`	Skip PRs with any of these GitHub labels. PRs matching these labels are not reviewed.

rules.ignorePatterns is deprecated. Use top-level excludePatterns instead — it is the canonical field for filtering files out of the diff. Existing .mergewatch.yml files keep working: any entries under rules.ignorePatterns are folded into excludePatterns at parse time and a one-time deprecation warning is emitted.

UX

The ux object controls how the review comment is formatted and what sections are shown.

Property	Type	Default	Description
`tone`	`string`	`collaborative`	Tone of review findings. One of: `collaborative`, `direct`, `advisory`.
`showWorkDone`	`boolean`	`true`	Show the “work done” stats bar (files scanned, lines reviewed, agents ran).
`showSuppressedCount`	`boolean`	`true`	Show how many findings were suppressed by the orchestrator’s dedup and quality filters.
`reviewerChecklist`	`boolean`	`true`	Show a reviewer checklist derived from the top findings.
`allClearMessage`	`boolean`	`true`	Show a special “all clear” message when there are no findings.
`commentHeader`	`string`	`""`	Custom Markdown header for the review comment. Replaces the default MergeWatch logo.

Tone directives:

Tone	Behavior
`collaborative`	Frames findings as suggestions from a teammate. Uses phrases like “Consider…”, “It might be worth…”, “One approach would be…”. Acknowledges the author’s intent before suggesting alternatives.
`direct`	States findings clearly and concisely without hedging. Leads with what needs to change and why. Skips pleasantries but remains respectful.
`advisory`	Presents findings as expert observations. Uses phrases like “In my experience…”, “A common pitfall here is…”, “Best practice suggests…”. Provides context for why the suggestion matters.

Path filters

MergeWatch has two top-level path-filter fields. They operate at different layers — see Skip Rules for the full picture.

Field	Layer	Default	What it does
`excludePatterns`	Diff filter	lock files, `dist/`, `build/`, `node_modules/**`, minified files	Files matching these globs are stripped out of the diff sent to agents. The PR is still reviewed if any non-matching files remain.
`includePatterns`	PR-skip override	`[]`	Forces a PR back into review even when every changed file would otherwise be classified as trivial (docs-only, lock-only). Files still flow through `excludePatterns` afterwards.

.mergewatch.yml

excludePatterns:
  - "**/*.generated.ts"
  - "**/fixtures/**"

includePatterns:
  - "SECURITY.md"
  - "docs/policy/**"

Agent-authored PRs

The agentReview object controls how MergeWatch handles pull requests authored by coding agents (Claude Code, Cursor, Codex, etc.). When detection matches, the review pipeline applies stricter prompts and tracks how many iterations the agent took to reach a passing state.

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Master switch for agent-authored PR handling. Set to `false` to disable detection entirely.
`strictChecks`	`boolean`	`true`	Inject the agent-mode prompt suffix when the PR is detected as agent-authored. The suffix warns reviewers about hallucinated APIs, no-op tests, and stale patterns.
`autoIterate`	`boolean`	`true`	Track iteration count across re-reviews and surface a “reviewer whisper” when an agent has taken multiple rounds to converge.
`maxIterations`	`number`	`3`	Iteration cap (1-20) used for the iteration-count metadata.
`passThreshold`	`string`	`noCritical`	Threshold an agent-authored PR must clear to be considered passing. One of `noCritical`, `noFindings`, `scoreAtLeast4`, `scoreAtLeast5`.
`detection.commitTrailers`	`string[]`	`["Co-authored-by: Claude"]`	Substrings searched in commit message trailers. A match flips the source to `agent`.
`detection.branchPrefixes`	`string[]`	`["claude/"]`	Branch-name prefixes that mark a PR as agent-authored.
`detection.labels`	`string[]`	`["ai-generated"]`	GitHub labels that mark a PR as agent-authored.

.mergewatch.yml

agentReview:
  enabled: true
  strictChecks: true
  passThreshold: scoreAtLeast4
  detection:
    commitTrailers:
      - "Co-authored-by: Claude"
      - "Co-authored-by: Cursor"
    branchPrefixes:
      - "claude/"
      - "cursor/"
    labels:
      - "ai-generated"

Pricing overrides

The pricing field maps a model ID to its per-token price (USD per 1M tokens) and is used by the cost-estimation pipeline. Set it when you run a model that is not in MergeWatch’s built-in price table — for example, a self-hosted Llama on Ollama or a custom Bedrock provisioned-throughput endpoint.

.mergewatch.yml

pricing:
  "custom-llama-3-70b":
    inputPer1M: 0.50
    outputPer1M: 0.75

Which model actually runs

model: is resolved against two other sources. Highest precedence first:

model: in this file — the per-repo setting documented above. The committed .mergewatch.yml always wins, consistent with every other key on this page.
An installation-level override, if one has been set on the repository’s installation record.
The deployment default, set per environment at deploy time.

Self-hosted differs in one respect: the LLM_MODEL environment variable is an operator pin rather than a default, so it overrides everything above — including this file. Omitting model: therefore means “use whatever this deployment is configured with”, not “use the value shown in the table above” — which is why the Default column reads (deployment default) rather than naming a model. The review log line records which source won:

[model] owner/repo#42 using us.anthropic.claude-sonnet-4-20250514-v1:0 (source=deploy-default)

Before MergeWatch v0.1.x, model: was silently ignored on the hosted service — the deployment default was used regardless of what this file said. Self-hosted always honored it. If you set model: and saw no change, that was why; it now works on both.

Minimal configuration

If the defaults work for you, the smallest valid configuration is:

.mergewatch.yml

version: 1

This enables all eight built-in agents with their default prompts, uses Claude Sonnet via Bedrock, and reviews PRs automatically.

Common patterns

Security-focused pipeline (e.g., payments service)

.mergewatch.yml

version: 1
model: us.anthropic.claude-sonnet-4-6
agents:
  style: false
  diagram: false
customAgents:
  - name: security-pci
    prompt: "This is a PCI-DSS scoped payments service. Focus on: SQL injection via raw queries, XSS in template rendering, hardcoded credentials, insecure cryptographic operations, and unvalidated redirects. Flag any use of eval() or exec()."
    severityDefault: critical
    enabled: true

Disables style and diagram agents. A custom agent adds domain-specific security checks for payments services.

Lightweight pipeline for high-volume repos

.mergewatch.yml

version: 1
model: us.anthropic.claude-haiku-4-5-20251001-v1:0
maxTokensPerAgent: 2048
maxFindings: 10
minSeverity: warning
agents:
  bugs: false
  style: false
  diagram: false

Uses the cheaper Haiku model, disables low-priority agents, and suppresses info-level findings. Good for repos with frequent small PRs where speed and cost matter more than comprehensive review.

Style-heavy pipeline for a frontend repo

.mergewatch.yml

version: 1
customAgents:
  - name: react-style
    prompt: "This is a React + TypeScript project. Flag any use of `any` type. Require explicit return types on exported functions. Flag inline styles — use Tailwind classes. Flag console.log() calls. Prefer named exports over default exports."
    severityDefault: warning
    enabled: true
  - name: frontend-security
    prompt: "Focus on XSS via dangerouslySetInnerHTML, unsanitized user input in URLs, and exposed API keys in client-side code."
    severityDefault: critical
    enabled: true

Custom agents add React/TypeScript conventions and frontend-specific security checks alongside the built-in agents.

Monorepo with service boundaries

.mergewatch.yml

version: 1
customAgents:
  - name: service-boundaries
    prompt: "This repo contains three services: payments/, orders/, notifications/. Flag any direct imports across service boundaries — each service must be independent. Flag shared mutable state."
    severityDefault: warning
    enabled: true
  - name: monorepo-style
    prompt: "Each service has its own tsconfig.json. Flag path aliases that reference other services."
    severityDefault: info
    enabled: true

Custom agents enforce architectural boundaries. All built-in agents remain enabled.

Review only on mention

.mergewatch.yml

version: 1
rules:
  autoReview: false
  reviewOnMention: true

MergeWatch stays silent until someone comments @mergewatch review on the PR.

Ignore generated code and vendored dependencies

.mergewatch.yml

version: 1
rules:
  ignorePatterns:
    - "*.lock"
    - "vendor/**"
    - "dist/**"
    - "generated/**"
    - "*.pb.go"
    - "*.gen.ts"

Django/Python backend

.mergewatch.yml

version: 1
customAgents:
  - name: django-security
    prompt: "This is a Django 5 project. Focus on SQL injection via raw querysets, CSRF token issues, unvalidated redirects, and mass assignment via ModelForm. Check for DEBUG=True in settings."
    severityDefault: critical
    enabled: true
  - name: django-style
    prompt: "Enforce PEP 8. Flag any print() calls — use logging instead. Flag bare except clauses. Require type hints on public function signatures."
    severityDefault: warning
    enabled: true
  - name: django-bugs
    prompt: "Watch for N+1 query patterns in Django ORM, missing database migrations for model changes, and unclosed file handles."
    severityDefault: warning
    enabled: true

Three custom agents with Django-specific prompts alongside the built-in agents.

Where the file lives

The .mergewatch.yml file must be placed at the root of the repository’s default branch (the branch GitHub shows when you visit the repo — usually main or master). MergeWatch reads the file from the default branch, not from the PR’s head branch. This means configuration changes in a PR do not take effect until they are merged.

If you rename your default branch, MergeWatch automatically detects the new default on the next webhook. No action is required.

`maxFileDiffKB`

Maximum size, in KB, of a single file’s diff section. Default 128. A file whose diff exceeds this is dropped from review even if no excludePatterns entry matches it. excludePatterns only catches artifacts you have already met. This catches the next one: a hand-written source file with a 128KB+ diff essentially does not exist, so a section that large is generated, vendored, or minified. Dropped files are always reported in the logs, distinctly from pattern exclusions — a pattern match is your intent, a size drop is MergeWatch’s.

maxFileDiffKB: 128   # set 0 to disable the size rule entirely

Related: MergeWatch also refuses to review a diff that would exceed the configured model’s context window, posting a neutral “Review skipped — diff too large” check that names the estimated size, the budget, and the model. Previously such a PR failed with a raw provider error.

Overview

Self-Hosting

LLM Providers

Platform Guides

Configuration

GitHub App

Deployment

Dashboard

Managed SaaS

Reference

.mergewatch.yml Reference

Configuration priority

Validation

Full annotated example

Property reference

Top-level properties

Agents

Custom agents

Rules

UX

Path filters

Agent-authored PRs

Pricing overrides

Which model actually runs

Minimal configuration

Common patterns

Where the file lives

`maxFileDiffKB`

​Configuration priority

​Validation

​Full annotated example

​Property reference

​Top-level properties

​Agents

​Custom agents

​Rules

​UX

​Path filters

​Agent-authored PRs

​Pricing overrides

​Which model actually runs

​Minimal configuration

​Common patterns

​Where the file lives

​maxFileDiffKB

Configuration priority

Validation

Full annotated example

Property reference

Top-level properties

Agents

Custom agents

Rules

UX

Path filters

Agent-authored PRs

Pricing overrides

Which model actually runs

Minimal configuration

Common patterns

Where the file lives

`maxFileDiffKB`