Merge request review¶
Outcome¶
You will know what Threadory's merge request review does, what context it uses, how and when it posts, and which settings change its behavior.
What the review does¶
For every merge request (GitLab) or pull request (GitHub) in a connected project, Threadory reads the diff and writes one summary comment on it: a short walkthrough of the change, the risks it sees, and a list of findings with the file and line each one refers to. A reviewer can then start from the summary instead of from the raw diff.
A review does not:
- approve, block, or merge anything — it is a comment, nothing more;
- push commits or change the branch; where a fix is small and exact, the comment
shows the replacement lines in a
suggestionblock for the author to apply; - open line-anchored threads on the diff. Findings are listed inside the single summary comment, with file and line references;
- replace a human review. Findings are claims to check, not verdicts.
Which context it uses¶
The review reads more than the diff. Before it writes the comment it collects:
- Linked work items. Tickets, issues, and sibling merge requests that Threadory has connected to this change — through references in the title, description, or comments. Explicitly linked items weigh more than items matched only by similarity; the review treats similarity matches as unverified guesses and does not hold the change to them. If a linked ticket states acceptance criteria that the diff does not address, the comment says so.
- Related project knowledge. Meeting notes, decisions, documents, and other items already synced into the project, found by search.
- Earlier threads. The review it posted before on the same merge request, and the discussion around it. A finding that the author argued and the review accepted, and any thread marked resolved, is treated as settled and is not raised again unless the new diff brings new evidence.
- The repository itself, for larger changes. When the sandbox runner is set up for your deployment and the change is large enough, the review can clone the source branch into an isolated sandbox and read the surrounding code, not just the diff. Small changes are reviewed from the diff alone. If the sandbox is not available, the review falls back to the diff-only path without an error.
When linked items exist, the comment ends with a Linked context section that lists them, so you can see what the review was told.
How it posts¶
- Summary comment. The review is posted as a regular comment on the merge request, under the identity of the token that connected GitLab (or of the Threadory GitHub App on GitHub).
- Published without approval by default. The review goes straight onto the merge request. If you prefer a human gate, turn off Publish without approval (see Settings): every review then waits in Approvals until someone approves it.
- Reply bot. When a person answers under the bot's review, Threadory can post one reply to that comment. On GitLab the reply goes into the same discussion thread and, when the reply settles the point, resolves the thread. On GitHub the reply is a regular pull request comment, because GitHub issue-level comments have no threads to resolve. Replies follow Auto-post ticket reviews & replies — with it off, each reply waits for approval. The bot never replies to its own comments or to system notes.
- Re-review on push. A new commit pushed to the branch produces a fresh review for the new head. The review sees the previous one, acknowledges what the new diff addresses, and concentrates on what changed and what is still open. If a push changes nothing worth saying, it stays silent.
- Trigger events. A review starts when a merge request is opened or reopened, when its head commit changes, or when its description is edited. It does not start for comments, approvals, label or title edits, merges, or closes — the merge request has to be open.
- One review per head. Repeated webhooks for the same commit do not produce duplicate comments.
- Force-push. GitLab often sends a force-push without saying what changed. Threadory does not treat that as "nothing happened": if the new head has not been reviewed yet, it is reviewed; if it already has been, the event is ignored.
Connect a source¶
| Source | How it connects | What the review needs |
|---|---|---|
| GitLab self-managed or gitlab.com | A project access token or personal access token, plus a project webhook. See Connect GitLab. | api scope: needed to post comments and to install the webhook. read_api is enough for reading only. |
| GitHub | The Threadory GitHub App installed on the repository; you authorize with GitHub during connection and pick the repositories. Beta. | The deployment must have the GitHub App configured. If the connector does not offer GitHub, ask your administrator. |
Without a webhook, GitLab falls back to hourly polling and the review arrives late. For the first-run walkthrough, see Your first review in five minutes.
Settings that exist today¶
Open Settings → Review. You need the admin role to change them.
| Setting | Default | Effect |
|---|---|---|
| Review merge requests | On | Master switch. Off keeps the bot out of the project's merge requests entirely — no review is generated and no model spend is incurred. |
| Publish without approval | On | On posts the review straight to the merge request. Off routes every review through the approval queue. |
| Audit rate | 0% | Share of published reviews that still go through approval as a spot-check. |
| Confidence floor | 50% | A review whose confidence is below this is dropped instead of posted. 0% publishes everything, including an unfinished review that found nothing. |
| Reply to human follow-ups | On | Lets the bot answer a person who comments under its review. |
| Auto-post ticket reviews & replies | On | Publishes ticket reviews and bot replies without approval. Merge request reviews have their own switch above. |
| Say so when a review does not finish | Off | Posts a note when a run stops before reaching a verdict, instead of staying silent. |
| Verify findings against the diff | On | A final pass removes claims the diff does not support. |
| One-click suggestion blocks | On | Lets the reviewer write suggestion blocks for clear mechanical fixes. |
| Agentic-exploration review | On | Lets the review read the repository in a sandbox (see above). The extra controls — model, maximum tool calls and requests, minimum change size — appear when it is on. |
| Review guidelines, Review tone hint, Reply tone hint, Learnings | Empty | Free text that the review reads as project context. Use guidelines for rules specific to your team, and learnings for short rules distilled from past feedback, one per line. |
Settings → Review Health shows whether reviews are completing.
Plan limits¶
Free plan limits apply; see the plans on threadory.ai. Your organization's plan and current usage are shown under Settings → Plan & Usage.
Limits of the review¶
- A very large diff is clipped before it reaches the model, so the review of such a change may not cover every file. Prefer smaller merge requests.
- It sees only what is connected and synced. A ticket that is not connected, or a decision made in a meeting that was never imported, cannot inform the review.
- It can be wrong. If a finding is incorrect, reply under it; the discussion is read by the next review of the same merge request.
Common problems¶
| Symptom | Likely cause | What to do |
|---|---|---|
| No comment appears on a new merge request | The webhook is missing, the review switch is off, or the review is waiting for approval | Check the webhook on the connector card, Review merge requests, and Approvals |
| The review arrives about an hour late | The project runs on polling | Install the webhook from the connector card menu |
| A push did not trigger a new review | The push did not change the head, or the review of that head already exists | Push a new commit; edits to labels or title do not trigger reviews |
| The comment does not mention a linked ticket | The ticket is not linked or not synced | Reference it in the title or description and run Sync now |
| Posting fails | The token lacks write access | Reconnect with the api scope |
Next step¶
Follow Your first review in five minutes, or see the integration matrix for connector status.