Code review

One review per push, written by the reviewers you define.

A code review is a kind: code_review file that names which pull requests to review and a list of reviewers, each a session with its own prompt, model, environment, and budget. Each push the file admits gets at most one review on the pull request, combining every reviewer's findings.

Review every push

Install the Ellipsis GitHub App on your repository, then commit this file to its default branch:

1
ellipsis:
2
kind: code_review
3
name: code-review
4
5
pull_requests:
6
draft: false
7
8
reviewers:
9
- name: bugs
10
claude_code:
11
prompt: Find bugs in this pull request.
12
model: claude-opus-5-5
13
- name: i18n
14
paths: ['frontend/**']
15
claude_code:
16
prompt: Flag user-facing strings that bypass the translation layer.
17
model: claude-sonnet-5-5
18
19
budget:
20
session: 3

Open a pull request to see it work. Each push starts the reviewers whose paths match the new commits, and one review from ellipsis-dev[bot] lands with their comments. A reviewer only sees commits it has not reviewed before, and a comment on a line outside those commits is held back. A push with nothing new for any reviewer starts nothing. Every review, with each reviewer's comments and session, is listed under Code Review in the dashboard.

What the review posts

Each reviewer marks every comment blocking or not. A review passes when no reviewer returned a blocking comment and fails otherwise. output sets the GitHub review submitted in each case:

1
ellipsis:
2
kind: code_review
3
name: code-review
4
5
reviewers:
6
- name: bugs
7
claude_code:
8
prompt: Find bugs in this pull request. Mark a comment blocking only when the change must not merge as is.
9
model: claude-opus-5-5
10
11
output:
12
on_pass: approve
13
on_fail: request_changes
14
summary: true

on_pass is silent (nothing is posted unless a reviewer left a non-blocking comment, which posts as a comment), comment, or approve; on_fail is comment or request_changes. A failed review posts its on_fail event whether or not any of its comments lands on a changed line. A review in which a reviewer stopped early never approves, and a pull request the Ellipsis app opened itself gets a comment in every case, because GitHub refuses an approval or a request for changes from a pull request's own author. With summary: true every reviewer also returns a summary, and the review body opens with it, above the platform's own details; the prompt says what the summary should contain. Without output, a pass is silent and a fail is a comment.

Configure a review

A file holds up to 64 reviewers, each with a unique name, and a repository holds one file. pull_requests takes the same filters as a pull request trigger. A reviewer takes the same environment, skills, and permissions blocks as an agent session; its budget takes only session. Every reviewer's GitHub token reads the contents and pull requests of the repository under review; permissions.github can add read scopes and repositories, never write, because the platform posts the review. See the Code review schema reference for complete examples and every field.

A file in the .ellipsis repository reviews every repository its pull_requests.repositories filter admits; a file in a repository reviews that repository and wins over the organization file. A file that breaks a limit or does not parse fails the sync, keeps the last good version running, and shows the error in the Ellipsis config check on the pull request.

PLACEHOLDER (Hunter): reviewers can share one prompt. Say that prompt takes text, path: prompts/find_bugs.md, or a list of text and files joined in order with a blank line between each, that a file is in the repository that holds this file or, with repository, in another one, that the file is read when the config syncs and again when the file changes, and that a missing, empty, or over 64 KiB file fails the sync.

1
ellipsis:
2
kind: code_review
3
name: code-review
4
5
reviewers:
6
- name: bugs-opus
7
claude_code:
8
prompt:
9
- path: prompts/codebase_context.md
10
- path: prompts/find_bugs.md
11
model: claude-opus-5-5
12
- name: bugs-sol
13
codex:
14
prompt:
15
- path: prompts/codebase_context.md
16
- path: prompts/find_bugs.md
17
model: gpt-6-sol
18
19
output:
20
on_pass: approve
21
on_fail: request_changes
22
23
budget:
24
session: 3

Each push starts both reviewers on the text of prompts/codebase_context.md followed by the text of prompts/find_bugs.md, one on Claude Code with claude-opus-5-5 and one on Codex with gpt-6-sol, and one review carries the comments of both. Start the two files from these templates, then rewrite prompts/codebase_context.md and the list under "What to consider" for your repository.

1
# About this project
2
3
`api-repo` is the HTTP API that `web-repo` and customers call. It is a Python service with a Postgres database.
4
5
These facts decide whether a change is safe here.
6
7
- A merge to `main` deploys to production.
8
- Migrations run before the new code starts, so a migration must work with the code that is already running.
9
- Customers call the endpoints under `/v1`, so a changed or removed field breaks them.
10
- Background jobs retry, so a job must be safe to run twice.
11
- Every table belongs to one account. A query that can return another account's rows is a blocking bug.
1
# Bug review
2
3
Find the bugs this pull request introduces. A bug is changed code that does the wrong thing for an input or a state that will really happen.
4
5
Look for logic errors, such as a wrong condition, a wrong default, or a value used before it is set. Look for failures the new code does not handle, such as an error, a timeout, an empty result, or a missing value. Look for two pieces of code that no longer agree, such as a caller and the function it calls, a writer and a reader of the same data, or a test and the behavior it claims to cover. Look for problems that depend on timing, such as a retry, a job that runs twice, or two requests at once. Look for changes that lose data, skip a permission check, expose a secret, or let one customer reach another customer's data.
6
7
Do not report style, naming, formatting, or a design you would have chosen differently.
8
9
## What to consider
10
11
- **Read past the diff.** Open the whole function and the file around each change. A change that looks right alone can break an assumption a few lines away.
12
- **Follow changed signatures.** When a function, a type, or a field changes its parameters, its return value, or its meaning, search the repository for every use and check that each one was updated, including tests, scripts, and other packages.
13
- **Consider second-order effects.** Ask what else reads the state this change writes, such as a database column, a cached value, a queued message, a config field, or an API response. Check that each reader still works.
14
- **Walk the failure paths.** For each new call that can fail, work out what happens on an error, a timeout, a missing value, and a retry, and what is left half written when it stops partway.
15
- **Inspect the dependencies.** When the change adds, upgrades, or newly relies on a library, a service, or a schema, read what it really does at the version this project pins instead of trusting its name.
16
- **Check what was removed.** Deleted code often carried a guard, a default, or a cleanup step. Find what still relies on it.
17
- **Picture it running twice.** Think through two requests in the changed code at once, the same job delivered twice, and old and new code running side by side during a deploy.
18
- **Read the tests against the change.** Check whether the tests run the new behavior or only pass because they fake the part that changed, and whether an edited assertion hides a regression.
19
20
## How the review works
21
22
You run on Ellipsis in your own cloud environment, with the repository checked out at the pull request's head commit. You are one of several reviewers. Each works alone, and Ellipsis merges every reviewer's comments into one review on the pull request. Ellipsis posts that review, so never post a comment yourself.
23
24
You review a range of commits, not the whole pull request. Ellipsis gives you a diff file that holds only the changes you have not reviewed. On the first push that is the whole pull request. On a later push it is only what is new, and the earlier commits are not yours to comment on again.
25
26
A comment can only land on a line in that diff. A comment anchored anywhere else is held back and the author never sees it. When the bug sits in code the pull request did not touch, such as a caller that was not updated, put the comment on the changed line that causes it and name the other file and line in the body.
27
28
The rest of the repository is there to read and search, and your GitHub access is read-only. The pull request's title and description come with your instructions. Read them to learn what the change is meant to do, then check whether the code does it.
29
30
Nobody answers questions during the session, and only the comments you return reach the author. The session has a budget, and a reviewer that runs out before it returns contributes nothing. Start with the riskiest parts of the change.
31
32
## What to report
33
34
Report a bug only when you can name the input or state that triggers it and what goes wrong. Write one comment per bug on the line that introduces it, say what breaks, and say how to fix it.
35
36
Mark a comment blocking only when the pull request must not merge as is. One blocking comment from any reviewer gets the push a request for changes. The push is approved only when every reviewer finishes with no blocking comment. When you find nothing, return no comments.

PLACEHOLDER (Hunter): the default repository, set with code_review.default_repository_id in the account settings, replaces the .ellipsis repository as the file that reviews every repository without its own.

What happens when a reviewer fails

A review posts at most 64 comments, and each reviewer returns at most 64. Change these with output.comments.max_per_review and output.comments.max_per_reviewer, or set comments.max on one reviewer. A reviewer that returns more than its limit fails and contributes nothing. Comments past the review limit are kept with the review but not posted. A blocking comment on a line the push did not change is held back but still fails the review, which posts its on_fail event with the comments that did land. When no reviewer finishes, nothing is posted and nothing is marked reviewed. A reviewer that fails or runs out of budget contributes nothing; the review still posts with the other reviewers' comments, never as an approval, and that reviewer covers the same commits again on the next push. When GitHub rejects the review, the review ends with status failed, nothing posts, and every reviewer covers the same commits again on the next push.

On this page

Schedule a demo