Concepts
How a review works
The five stages every pull request goes through, from webhook to verdict.
Overview
Every review runs the same five stages. The API receives the GitHub event and queues a job; a separate worker runs the review and posts the result.
01
Trigger
02
Context
03
Agents
04
Filter
05
Post
1. Trigger
GitHub calls POST /api/v1/webhook/github for pull request events. OpenMerge verifies the X-Hub-Signature-256 header, then starts a review only for these actions:
| Action | When it happens |
|---|---|
opened | A pull request is created. |
synchronize | New commits are pushed to the pull request. |
reopened | A closed pull request is reopened. |
The event is ignored when the repository is not connected, automatic review is paused for it, or the GitHub App installation is suspended.
Each review is tied to one commit. If a review for the same repository, pull request, and head commit is already running or finished, OpenMerge does not start another. When the review is queued, a Review in progress note is posted on the pull request.
2. Context
The worker fetches the pull request, its diff, and the changed files, clones the repository, and then gathers five kinds of context in parallel:
| Source | What it adds |
|---|---|
| AST summaries | The functions, classes, and types the change touches. |
| Code graph | Where the changed symbols are used elsewhere in the repository. |
| Resolved imports | The modules the new code depends on. |
| Linter output | Existing warnings on the changed files. |
| PR history | Earlier pull requests that touched the same files. |
3. Agents
The code, security, and performance agents run at the same time on the same diff and context. Each one returns findings with a file, a line in the new version of the file, a severity, a category, an explanation, and, where it helps, replacement code. See Agents and severity.
4. Filter
- Duplicates are dropped: two findings on the same file and line with the same opening text count as one.
- Findings are ranked from Critical to Info.
- Blocking findings (High and Critical, unless an agent marks one non-blocking) go first.
- The list is capped at 12 comments per review.
5. Post
Findings are posted as inline comments on the changed lines, and the progress note is replaced by the summary. The session, its findings, and its timing are saved, so the review appears on your dashboard. See Reading a review.
Retries and recovery
- A failed attempt is retried automatically with exponential backoff, up to 10 attempts. The dashboard shows these as Retrying.
- Workers send heartbeats while reviewing. If a worker stops, the stalled review is recovered and queued again.
- If every attempt fails, the review is marked Needs attention with the last error. See Troubleshooting.
Something unclear or out of date? Open an issue.