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.

​
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.

​
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 match ignorePatterns — If every file in the PR matches a pattern in rules.ignorePatterns, the entire PR is skipped.
  • PR exceeds rules.maxFiles limit — PRs with more changed files than the configured maxFiles value (default: 50) are skipped with a comment explaining why.
  • Repository is paused — If MergeWatch is paused for the repository in the dashboard, no reviews run until it is resumed.

​
Review status values

Every review tracked by MergeWatch has one of the following statuses, visible in the dashboard Reviews table:
StatusMeaning
Reviewing…The ReviewAgent Lambda is currently running. The review is in progress.
ReviewedThe review completed successfully and findings have been posted to GitHub.
SkippedThe PR matched a skip rule. The reason is logged and visible in the detail drawer.
FailedA Lambda error or Bedrock failure occurred. The review can be re-triggered.
Failed reviews can always be retried by commenting @mergewatch review on the pull request.

​
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

To manually re-trigger a review, post a comment on the pull request: 
@mergewatch review
This works in all scenarios:
  • Even when autoReview: false is set in your configuration
  • 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: 
@mergewatch summary
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.
RangeInterpretation
90-100High confidence — obvious, clear-cut issue
75-89Medium-high confidence — likely a real issue
50-74Lower confidence — suppressed by the orchestrator
1-49Low confidence — suppressed by the orchestrator
The orchestrator automatically drops all findings with confidence below 75 during the dedup and ranking phase. This threshold is not user-configurable — it is designed to minimize false positives while surfacing real issues.
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.