> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gentic.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatic Code Review

> Enable a separate reviewer agent to test, review, and gate pull requests before you see them, and how to observe, recover, and turn it off.

Automatic Review runs a second, isolated coding agent against a pull request's exact commit, tests and inspects it, and posts a real GitHub review — approving it, requesting changes (which are routed straight back to the original implementation agent), or leaving non-blocking comments. It is alpha, opt-in, and off by default.

<Note>
  This page covers the owner-facing behavior and controls. For the
  underlying design decisions, see `docs/adr/0003` through `0010` in the
  repository.
</Note>

## Enabling it

Automatic Review has two levels of configuration, both under **Settings → Workspace**:

* **Project-level** `automatic_review_enabled` (plus an optional reviewer provider, model, and custom instructions) is the default for every issue in that project.
* **Issue-level** override lets a single issue opt in or out regardless of the project default.

<Warning>
  **The setting only matters before an issue has its first pull request.**
  The moment a PR is associated with an issue, Gentic takes an immutable
  snapshot of whatever the effective setting was at that instant
  (`issue_review_policies`) and reviews that issue against the snapshot for
  the rest of its life. Changing the project or issue setting afterward —
  in either direction — has **no effect** on an issue that already has a
  PR. There is no retroactive enable or disable.
</Warning>

This means: if you want an issue reviewed automatically, the setting must be on *before* its agent opens a pull request. If you turn it on after the fact, that issue's existing PR was never eligible and never will be — only issues that get a PR after the change will pick it up.

## What happens during a review

1. A pull request opens, updates, or its required CI finishes — Gentic re-evaluates eligibility on every one of these events.
2. If eligible, a **Review Cycle** starts for that pull request's exact head commit, with a budget of **3 attempts**.
3. A reviewer agent — a separate process from the one that wrote the code, with no push access and no Gentic MCP tools — clones that exact commit into a disposable checkout, inspects and can run local tests, and produces a verdict.
4. The verdict is published as a real GitHub pull request review:
   * **Approved** — counts toward the issue being presented as `Approved` (see [Multiple pull requests](#multiple-pull-requests) below).
   * **Changes requested** — findings are delivered as a new message to the *same* implementation session that opened the PR, and the issue returns to `Todo`. This consumes one of the 3 attempts.
   * **Commented** — non-blocking feedback; the issue returns to `Ready for review`.
5. Every push while a review is in flight cancels the stale run without spending an attempt and re-evaluates at the new commit. A push after a cycle has already concluded (approved, exhausted, or superseded) starts a **fresh** cycle with a full 3-attempt budget.
6. A genuine human GitHub review requesting changes always wins immediately — it supersedes any in-flight or already-approved automatic cycle. (The automatic reviewer's own review, echoed back through the same webhook, is recognized and ignored so it can't supersede itself.)

### Pull requests no issue produced

Automatic Review is not limited to pull requests an agent opened. When it is enabled on a project, **every pull request against that project's repository is reviewed** — a branch you pushed by hand, a teammate's work, a dependency bump.

A pull request that no issue produced has nothing to hang a review on, so Gentic creates one: a **tracking issue** titled `PR #<number>: <pull request title>`, in the project that owns the repository. It behaves like any other issue with an open pull request — the review runs against it, its status follows the pull request (`Reviewing` → `Approved` or `Changes requested`, then `Merged` or `Cancelled` when the pull request closes), and the review appears on GitHub as usual.

A tracking issue is **review-only**: no agent is ever put to work on it. Requested changes are published on the pull request and stop there, and neither failing CI nor a reviewer's comment queues an agent run the way they do for an issue an agent implemented — there is no agent session behind a hand-written branch to hand any of it to. You act on the review yourself; your next push starts a fresh review cycle.

Three kinds of pull request are deliberately left alone, with no tracking issue and no review:

| Not tracked                                     | Why                                                                                                                                                                                         |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Drafts, and closed or merged pull requests      | Nothing to review — a draft can't hold a review run at all. A draft marked **Ready for review** is picked up at that moment.                                                                |
| Pull requests from a **fork**                   | Reviewing runs the branch's code and tests on your host. For a fork that is an outside contributor's code running on your machine, which the reviewer's isolation does not sandbox against. |
| Anything in a project with Automatic Review off | The project setting is the only switch; nothing opts in separately.                                                                                                                         |

<Note>
  Turning Automatic Review on for a project therefore also starts creating
  tracking issues for new non-agent pull requests in its repository. It is not
  retroactive: a pull request that was already open when you enabled it is
  picked up on its next push, not immediately.
</Note>

### Multiple pull requests

If an issue has more than one open, non-draft associated pull request, every one of them must independently reach an approved Review Cycle before Gentic presents the issue's overall status as `Approved`.

### What decides `Approved`

With Automatic Review enabled, the Review Cycle is what decides the issue's `Approved` status — not GitHub's own review decision. This matters because GitHub only reports a review decision for repositories whose branch protection *requires* reviews; everywhere else it reports nothing at all, however many approvals a pull request carries. So an automatic approval holds on any repository, and it holds even where branch protection is still waiting on a human approval before the merge button unlocks. A human review requesting changes, or failing or in-flight CI, still outranks it.

### Infrastructure failures

A crash, timeout, or malformed reviewer output is never treated as a verdict. It retries automatically once at the same commit; if that retry also fails, automatic progress stops and the Review Cycle is left `Active` with no live run, waiting for a human action or new code — see [Recovery actions](#recovery-actions).

## Observability

* **Issue timeline** — every lifecycle transition (`review_queued`, `review_started`, `review_approved`, `review_changes_requested`, `review_failed`, `review_superseded`, `review_fix_delivered`) appears as a timeline event on the issue, including *why* (e.g. superseded by a human review vs. a new push).
* **Review Run logs** — each reviewer execution streams its own log (separate from the issue's chat), viewable from the issue.
* **GitHub itself** — the published review, its verdict, and any inline/summary comments are ordinary GitHub review data, subject to your repository's own branch protection and required-review settings, which remain authoritative regardless of what Gentic shows.

## Recovery actions

These appear directly on the issue when applicable:

| Control                                | When it appears                                                                                                                                                        | What it does                                                                                                                                 |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Retry review**                       | The active cycle has no live run and hasn't exhausted its 3-attempt budget (typically after two consecutive infrastructure failures)                                   | Queues a fresh review run at the current commit, same cycle, same budget                                                                     |
| **Continue with human review**         | The pull request has an active Review Cycle                                                                                                                            | Marks the cycle approved without a further automatic verdict — the only other way (besides an automatic approval) a cycle reaches `Approved` |
| **Start fresh implementation session** | The durable owner of the implementation session can't resume (agent/model changed, no resumable session was ever recorded, or the original host was deleted or banned) | Abandons the old session and starts a new one to pick up the next review fix                                                                 |

A cycle that has already exhausted its 3 attempts, been superseded, or been approved needs no recovery action — the next push (or **Continue with human review**) is what moves it forward.

## Troubleshooting

### Every review fails with `403 Resource not accessible by integration`

The reviewer ran and produced a verdict, but Gentic could not post it: the
GitHub App installation has read-only access to pull requests. Publishing a
review is the only write Gentic performs against the GitHub API, so an
installation set up before Automatic Review existed reads PR and check
events perfectly well and still fails at this last step.

Fix it by raising the app's **Pull requests** permission to **Read & write**
and then accepting the resulting permission request on the installation —
both halves are required. See
[GitHub Integration](/web/github-integration#connect-github) for the full
permission table.

Each failed publish consumes the cycle's attempt budget, so after fixing the
permission use **Retry review** on any issue whose cycle still has attempts
left, or push a commit to start a fresh cycle on one that exhausted them.

## Turning it off (safe disablement)

* **New work**: flip the project or issue setting off. Any issue that has **not yet** opened a pull request picks up the change immediately.
* **An issue with an already-open pull request**: the setting change does not reach it (see the immutability note above). To stop automatic review on that specific issue, use **Continue with human review** — this forces the current cycle to `Approved` and nothing further is automatically queued for it. Closing or merging the pull request has the same practical effect, since there is no live PR left to evaluate.
* **Whole-workspace kill switch**: there isn't a single switch that pauses every in-flight cycle at once. Disabling the project setting stops new issues from opting in; issues already mid-cycle need the per-issue action above (or to be closed/merged) to stop.

This asymmetry — instant for new work, requiring an explicit per-issue action for work already in flight — is intentional: it mirrors how the policy snapshot itself works, and it guarantees a review that's already running is never silently abandoned mid-flight by an unrelated settings change.