Skip to main content
The Settings page controls review behavior for all repositories in the current installation. These settings act as defaults — a .mergewatch.yml file in any repository overrides them for that repo.

​
Who can edit

Only GitHub org owners (or personal-account installation owners) can modify settings. Non-admins see the full Settings page in read-only mode with a banner explaining why all fields are disabled.
Admin status is verified server-side on every PUT /api/settings request by calling the GitHub API live. Even if the UI is manipulated, the API rejects changes from non-admin users with 403 Forbidden.

​
Precedence

Settings configured here apply to all repositories in the installation. A .mergewatch.yml file checked into a repository always takes precedence. See Configuration priority for the full resolution order.

​
Schema

The stored settings object (InstallationSettings in @mergewatch/core) has the following shape and defaults:
FieldTypeDefaultDescription
severityThreshold"Low" | "Med" | "High""Med"Minimum severity level to post as a comment. Findings below this threshold are suppressed.
commentTypes.syntaxbooleantrueInclude syntax-category findings.
commentTypes.logicbooleantrueInclude logic / bug-category findings.
commentTypes.stylebooleantrueInclude style-category findings.
maxCommentsnumber (1–50)10Upper limit on findings posted per PR. Prevents noisy reviews on large changesets.
summary.prSummarybooleantruePost a high-level summary comment on each PR.
summary.confidenceScorebooleantrueShow the AI confidence score in the summary.
summary.issuesTablebooleantrueAdd a severity-ranked table of all findings to the summary.
summary.diagrambooleantrueRender a Mermaid architecture diagram in the summary comment.
customInstructionsstring (≤ 1000 chars)""Free-text instructions injected into every agent prompt.
commentHeaderstring""Optional header line prepended to every MergeWatch comment. When empty, MergeWatch uses its built-in header.
Use custom instructions to encode team-wide conventions: “We use structured logging — flag any use of console.log in production code” or “All API endpoints must validate input with Zod schemas.” The live character counter enforces the 1,000-character cap.

​
Comment header

The Comment header field sets a line prepended to every MergeWatch comment. It supports Markdown. A live preview below the input shows how it renders on GitHub. When left blank, MergeWatch posts its standard header.

​
Saving changes

The Save button activates only when you have unsaved changes. It is permanently disabled for non-admin users.
1

Make changes

Modify any setting on the page. The Save button becomes active and shows unsaved changes.
2

Click Save

The dashboard sends a PUT request to /api/settings?installation_id=.... The server re-verifies your admin status against GitHub before applying changes.
3

Confirmation

A success toast confirms the settings were saved. Changes take effect on the next PR review — in-progress reviews use the settings that were active when they started.

​
Validation

The API rejects requests that fail any of the following checks with 400 Bad Request:
  • severityThreshold must be one of Low, Med, High.
  • maxComments must be a number between 1 and 50 (inclusive).
  • customInstructions must be a string of at most 1,000 characters.

.mergewatch.yml Reference

Override any installation-level setting on a per-repo basis.

Custom Instructions

Detailed guide on writing effective custom instructions for the review agents.