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

# Merge gates

> Require Otto's review or approval before a pull request can merge.

Otto posts checks you can require in branch protection. Pick the one that matches what you want to enforce:

| You want to… | Require |
| - | - |
| Wait until Otto has finished reviewing | [Otto Review](#github-the-otto-review-check) (GitHub) or [`otto/review`](#azure-repos-the-otto/review-status) (Azure Repos) |
| Merge on **either** Otto's approval or a human's | [Otto Approval](#the-otto-approval-check) (GitHub only) |

## GitHub: the Otto Review check

Whenever Otto starts a fresh review of a PR's head commit, it adds an **Otto Review** check to that commit. A fresh review happens when a PR is opened, a commit is pushed, a review is requested, or someone comments `/otto re-review`. Replies to comments don't touch the check.

The check says whether Otto is still reviewing. It never reflects Otto's verdict, which lives in the review itself.

| State | Meaning |
| - | - |
| In progress | Otto is reviewing this commit. |
| ✅ Success | Otto finished reviewing (approved, requested changes, or commented). |
| ⚪ Neutral | Otto didn't finish or skipped the review: it errored, timed out after 60 minutes, the workspace is out of credits, a [skip rule](/configuration/skipping-reviews) matched, or the PR was too large to review automatically. The check's summary says which. |

GitHub treats success and neutral as passing, so a finished or failed Otto review never blocks a merge. Comment `/otto re-review` to retry after a neutral result.

### Require it

In the repository's branch protection rule or ruleset, under **Require status checks to pass**, add `Otto Review`.

<Warning>
  A required check that never appears blocks the merge ("Expected — Waiting for
  status to be reported"). Otto only adds the check to commits it reviews, so it
  won't appear if PR reviews are paused for the workspace, or when a push lands
  on a PR Otto hasn't commented on yet. Only require it on repositories where
  Otto reviews every PR.
</Warning>

## The Otto Approval check

GitHub doesn't count approvals from apps like Otto toward a branch's required reviews, and rulesets can't express "one human approval **or** Otto's approval". The **Otto Approval** check puts that OR into a single check, so a repository can require the check instead of a human review.

Turn it on in **Settings → Reviews → Otto Approval check** (owners and admins). It's off by default and applies only to GitHub pull requests.

| State | Meaning |
| - | - |
| Queued | A review of this commit is waiting, for example during the short delay after a push. |
| In progress | Otto is reviewing this commit. |
| ✅ Success | Otto approved this commit, **or** someone with write, maintain, or admin access approved it. |
| ❌ Failure | Otto requested changes or only commented, couldn't finish (error, timeout, out of credits, PR too large), skipped the PR, or didn't review the commit. |

* **Either approval is enough.** A human approval passes the check even if Otto requested changes on the same commit.
* **Approvals are per commit.** Only approvals of the PR's latest commit count. A reviewer's later request for changes, or a dismissed review, removes their approval. The PR author and bots never count.
* **Otto's latest decisive verdict counts.** If Otto approves in a follow-up reply (for example, after you fix or refute its findings), the check turns green; a later request for changes turns it red. A comment-only reply doesn't change it.
* **It fails closed.** If Otto can't review a commit, the check fails rather than passing, so an outage never lets a PR merge unreviewed. Push a fix, comment `/otto re-review`, or get a maintainer's approval.
* **Your `otto.yml` approval policy applies.** With [`approve_up_to: none`](/configuration/approval-policy), Otto never approves, so a human approval is always needed.

### Require it

In the repository's ruleset or branch protection rule:

1. Set **Required approvals** to `0`.
2. Under **Require status checks to pass**, add `Otto Approval` and select Otto's GitHub App as the expected source.

### What changes when it's on

* Otto reviews **every push** to an open, non-draft PR in the repositories it covers, not only PRs it has already commented on, so every commit gets a check. This uses more review credits.
* Pushes from bots (other than allowlisted ones such as Dependabot and Renovate) aren't reviewed. Their commits get a failing check that a maintainer approval clears.
* Repositories Otto doesn't review, or every repository while PR reviews are paused, get a failing check that a maintainer approval clears.
* PRs that were already open get the check on their next push, re-review, or human review.

<Warning>
  **Turning it off:** remove `Otto Approval` from your required status checks
  first. Once the setting is off, Otto stops adding the check to new commits,
  and a required check that never appears blocks the merge forever.
</Warning>

## Azure Repos: the otto/review status

Whenever Otto starts a fresh review, it posts an `otto/review` status on the PR iteration it's reviewing. A fresh review happens when a PR is created, when commits are pushed (if your reviewer listens to PR updates), or when someone comments `/otto review`. Replies to comments don't touch the status.

The status says whether Otto is still reviewing. It never reflects Otto's verdict, which Otto records as its reviewer vote.

| State | Meaning |
| - | - |
| Pending | Otto is reviewing this iteration. |
| Succeeded | Otto finished reviewing (approved, requested changes, or commented). |
| Not applicable | Otto couldn't finish or skipped the review: an error, a 60-minute timeout, a PR that was too large, a skip rule, or no credits. |

A required status policy treats "not applicable" as not applying to the PR, so a finished or failed Otto review never blocks completion. Comment `/otto review` to retry.

### Require it

Add a status check policy to the target branch (**Branch policies → Status checks → +**):

| Setting | Value |
| - | - |
| Status to check | `otto/review` |
| Policy requirement | Required |
| Authorized identity | Otto's service principal, so only Otto can satisfy the policy |
| Reset conditions | Optional; see the warning below |
| Policy applicability | Apply by default |

<Warning>
  A required status that is never posted blocks completion. Otto only posts it
  on PRs it reviews, so require it only on branches where Otto reviews every PR.
  With **Reset status whenever there are new changes** on, every push resets the
  policy until Otto reviews the new iteration. Only turn it on if Otto
  re-reviews on PR updates; otherwise each push blocks the PR until someone
  comments `/otto review`.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.