GitHub Integration
Install the Otto Detective GitHub App and Otto reviews the pull requests in the repositories you choose. Otto reviews and comments. It never commits, pushes, or merges.
Installing the GitHub App
- In Otto onboarding, click Connect GitHub (or go to Settings → Integrations later)
- Install the Otto Detective GitHub App on your organization
- Choose which repositories Otto can access
- All repositories: Otto reviews pull requests in every repository
- Only select repositories: Otto reviews only the ones you pick
- Return to Otto. Reviews are enabled automatically for the repositories you granted
You can change the repository selection in GitHub at any time, and turn reviews off for an individual repository from its project page in Otto.
Permissions
The Otto Detective GitHub App requests:
| Permission | Why |
|---|---|
| Contents (read) | Read the code under review |
| Pull requests (read/write) | Post reviews, inline findings, and replies |
| Issues (read/write) | Post and answer pull request comments |
| Checks (read/write) | Post the Otto Review and Otto Approval checks |
| Metadata (read) | Read basic repository information |
It only reviews the repositories you select.
What Otto posts on a pull request
- A native review. Otto approves, requests changes, or comments.
- Inline findings on the lines that changed, ranked P0–P3, each with a one-click suggested change and a prompt you can paste into your AI coding tool. A suggestion only lands when someone clicks Apply.
- One living summary per pull request, headed Otto Summary, with the verdict, findings, a change-flow diagram, and Merge confidence: X/5. Each new review updates the same summary. If you prefer a new summary for every review, change the comment style in your review settings.
- The Otto Review check on the commit under review.
Otto also adds itself to the pull request's Reviewers, so GitHub's Re-request review button asks Otto for a fresh review.
When Otto reviews
- When a pull request opens, whatever the base branch, including Dependabot and Renovate PRs
- When a draft is marked ready for review (drafts wait)
- When you push new commits, review is re-requested, or someone comments
/otto reviewor/otto re-review
Pull requests that change more than 100 files are skipped automatically. Comment /otto review to run one anyway.
Talking to Otto
Reply to any of Otto's comments, mention @otto-detective, or start a comment with /otto review, /otto re-review, or /otto explain. Otto answers in the thread and remembers what you have told it on that pull request.
The Otto Review check
Whenever Otto starts a fresh review of a pull request's head commit, it adds an Otto Review check to that commit. The check says whether Otto is still reviewing; the verdict 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 couldn't finish: it errored, timed out (after 60 minutes), or the org is out of credits |
GitHub treats success and neutral as passing, so the check never blocks a merge on its own. Comment /otto re-review to retry after a neutral result.
Waiting for Otto before merging
To stop merges while Otto is reviewing, add Otto Review as a required status check in the repository's branch protection rule or ruleset.
A required check that never appears blocks the merge. Otto only adds the check to commits it reviews, so only require it on repositories where Otto reviews every pull request.
The Otto Approval check
GitHub doesn't count an app's approval toward a branch's required reviews. The opt-in Otto Approval check passes when Otto approves the pull request's latest commit, or when someone with write, maintain, or admin access approves it. A repository can require this 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. Then, in the repository's ruleset, set Required approvals to 0 and add Otto Approval as a required status check from Otto's GitHub App.
Unlike Otto Review, this check fails closed: if Otto can't review a commit, the check fails until Otto or a maintainer approves. With it on, Otto reviews every push to an open, non-draft pull request, which uses more review credits.
Before turning the setting off, remove Otto Approval from your required status checks. Otherwise the missing check blocks merges.
Tuning reviews
- Review depth: Light, Standard, Deep, or Max, in your review settings. It applies to the next review.
- Review instructions: tell Otto what matters to your team, such as areas to focus on, conventions to enforce, or things to skip.
- Per repository: commit an
otto.ymlfile to set depth and instructions per path, ignore files, or skip automatic reviews.