Skip to main content
MergeWatch listens to GitHub webhook events and automatically reviews pull requests based on a set of configurable rules. This page explains exactly when reviews run, what statuses they produce, and how to control the lifecycle.
This page covers when reviews run. What happens to a finding after an agent produces it — grounding, dedup, consolidation, the convergence guard, linter deference — is covered in How MergeWatch avoids false positives. If reviews feel noisy or repetitive, start there.

​
When reviews trigger

MergeWatch triggers a review when it receives any of the following GitHub webhook events:
1

pull_request.opened

A new pull request is opened against the repository. MergeWatch fetches the diff and starts a review immediately.
2

pull_request.synchronize

New commits are pushed to an existing pull request. MergeWatch re-reviews the updated diff and replaces the previous summary comment.
3

pull_request.reopened

A previously closed pull request is reopened. MergeWatch treats this the same as a new PR and runs a fresh review.
4

pull_request.ready_for_review

A draft pull request is marked as ready for review. MergeWatch treats this the same as a new PR and runs a fresh review.
5

issue_comment.created (manual trigger)

A comment is posted on a pull request mentioning @mergewatch. MergeWatch recognizes three mention commands:
  • @mergewatch review — triggers a full review (all agents)
  • @mergewatch summary — triggers a summary-only review (summary agent only)
  • @mergewatch (any other mention) — triggers a conversational response. MergeWatch reads the PR diff and its previous review findings, then replies directly to the user’s comment using the LLM. No review pipeline runs — the response is posted as a regular PR comment. Use this to ask questions about findings, request clarification, or discuss specific parts of the code.
All mentions are case-insensitive. This works even when autoReview is set to false in your configuration.A fourth command, /mergewatch reject, records a finding as an explicit dispute rather than triggering a review — see feedback signals.

​
When reviews do NOT trigger

MergeWatch deliberately skips reviews in the following situations:
  • Draft PRs — Skipped by default. Set rules.skipDrafts: false in your .mergewatch.yml to review drafts.
  • All changed files are built-in trivial — If every file in the PR matches MergeWatch’s built-in trivial-paths list (lock files, docs, build artifacts, editor/CI config), the PR is skipped. Use includePatterns to opt specific paths back in.
  • PR exceeds rules.maxFiles limit — PRs with more changed files than the configured maxFiles value (default: 50) are skipped with a comment explaining why.
  • Billing blocked (managed SaaS) — Once the free tier is used up, reviews require a balance above the minimum. Below it, reviews are blocked before the model is called rather than run and billed. See Billing.

​
Review status values

Every review tracked by MergeWatch has one of the following statuses, visible in the dashboard Reviews table:
Failed reviews can always be retried by commenting @mergewatch review on the pull request.

​
What the GitHub check run shows

MergeWatch posts a single MergeWatch Review check run on every reviewed commit. Its title leads with the merge score so the verdict is visible from the checks tab without opening the summary comment:
Only verified critical findings fail the check. A critical the verification pass could not confirm is reported as an advisory concern and the check still succeeds — the score is clamped instead, so a green check never means “the review found nothing worth reading”. Read the score in the title.

​
Comment editing behavior

MergeWatch manages comments on your pull requests as follows:
  • Summary comment — MergeWatch creates one summary comment per PR and edits it in place on every subsequent re-review. This keeps the conversation clean and avoids flooding the PR with duplicate summaries.
  • Inline findings — Individual findings are posted as fresh review comments on the relevant lines of code. Each re-review posts a new set of inline comments.
  • Old inline comments are not deleted — Due to a GitHub API limitation, MergeWatch cannot delete previously posted inline comments. They remain on the PR but are superseded by the latest review.
If you see outdated inline comments after a re-review, check the timestamp. The most recent review’s summary comment always reflects the current state.

​
Re-triggering a review

There are two ways to manually re-trigger a review: Comment on the pull request:
Click the GitHub Checks UI “Re-run” button on the MergeWatch check run. MergeWatch listens for check_run.rerequested and re-runs the same review pipeline that produced the original check. Both paths work in all scenarios:
  • Even when autoReview: false is set in your configuration. In this mode MergeWatch leaves no trace on the PR at all — no reaction, no check run, no comment — so a mention is the only way to get a review. See Auto-review off.
  • After a failed review to retry
  • After pushing new commits, if you do not want to wait for the automatic trigger
  • On PRs that were previously skipped (the skip rules are re-evaluated)
When a re-triggered review completes, it replaces the previous summary comment with the new results. Inline findings are posted fresh alongside any existing comments. To request only a summary without a full review:
This runs the summary agent only and posts a high-level overview of the PR without inline findings.

​
Confidence scores

Each finding produced by MergeWatch includes a confidence score from 1 to 100, indicating how certain the agent is about the issue. Findings with confidence below the floor (75 by default) are dropped. The orchestrator prompt asks for this, and a deterministic filter enforces it afterwards — a prompt instruction alone was not reliable enough to depend on, so the floor is applied in code regardless of what the orchestrator returns. The threshold defaults to 75 and is configurable per repo with minConfidence (1—100). Lower it (e.g. minConfidence: 50) to surface the speculative tier shown above as suppressed; raise it to report only near-certain defects. The default is set to minimize false positives while surfacing real issues; see How MergeWatch avoids false positives for the other guards that run alongside it.
If you notice a legitimate issue being suppressed, consider adding a custom agent with a targeted prompt. Custom agents with focused prompts tend to produce higher-confidence findings for domain-specific concerns.

​
Next steps

Skip Rules

Learn how to control which PRs are skipped and why.

Custom Instructions

Tailor review focus with project-specific guidance injected into agent prompts.