Code review
Ask for a review, comment on lines of a diff, approve or request changes, and settle threads from the web app or the CLI.
Review a pull request
Read the diff, leave a comment on a line, then give a verdict.
sailfork pr diff 12
sailfork pr review 12 --request-changes \
--body "The migration drops a column that is still read." \
--inline "src/db.rs:41:This drops the column."
sailfork pr review 12 --approve Line comments are posted first, then the verdict. A verdict is one of two choices: approve, or request changes. A comment on its own is not a verdict.
Ask for a review
A pull request has one reviewer. The author, or anyone with push access, sets it:
- In the web app, open the merge panel, find Reviewer and choose Ask someone, then pick a person. Anyone who can read the repository qualifies.
- From the CLI, use
sailfork pr create --reviewer adawhen you open it, orsailfork pr edit 12 --reviewer adalater.
The pull request then appears in the reviewer's sailfork status under "Waiting for your review". See Notifications and activity. A draft asks nobody until it is marked ready.
Review in the web app
The Changes section of the pull request page is the diff. Switch between Unified and Split, and tick Viewed on a file to mark it done.
- Comment on a line: choose its line number. Shift-click another line number to comment on a range. Click a number on the old side to comment on a line that was removed.
- Comment on words: select text in the diff and choose Comment on this. The thread is anchored to the selected characters, which stay highlighted in the diff and quoted on the thread. A selection across lines anchors to the range of lines. See the API for the fields.
- Use the line menu: right-click a line or a selection, or press Shift+F10 on a focused line number. The menu offers Comment on line N (Comment on the selection for words), Suggest a change on a line of the new side, Copy the line (or Copy the selection), Copy a link to this line, Copy the file path, View the file at line N and Mark the file viewed. Links and text fields keep the browser's menu.
- Start a thread: write the comment and send it. Later comments on the same line join the thread. Use Reply under a thread to answer it.
- Edit or delete: you can edit and delete your own comment, and anyone with push access can delete or fold away any comment. A folded comment shows Show it, and Show it again hides it once more.
- Give a verdict: in the merge panel, write in Your review ("What you checked, or what to change"), then choose Approve or Ask for changes. Ask for changes needs text. After you approve, the button reads Approved.
Send comments together
Choose Start a review next to Comment to save a comment as pending instead of posting it. While a review is open, each new comment and reply reads Add to review, with Comment now and Reply now to post one at once. The merge panel shows "Your review has N pending comments".
Pending comments are saved on every device you use and nobody else sees them. Send N comments posts them all. Approve or Ask for changes sends them together with your verdict. Discard drops them all. Starting a review needs a signed-in account. From a script, POST .../reviews takes the line comments and the head commit you reviewed in one call and lands all of them or none: see Submit a review.
See who is on the pull request
Faces under the pull request's title show who else has it open. Hover them to see what each person is doing, such as reading a file or writing a comment. The file list and each file header show who is on that file, and a line someone is commenting on is marked in the diff with their face. Your own other tabs are left out. An integration or agent shows under its client name, announced through PUT .../presence: see Presence. Presence is never stored.
A review's text appears in the Conversation section as its own entry, not attached to a file.
On your own pull request the box reads Your self-review. When an agent opened the pull request under your account, this is where you read what it wrote before anyone else does. Your verdict shows as "self-reviewed and approved" or "self-reviewed and asked for changes". It never counts toward the approvals from people the merge rules ask for. It meets the Author self-review rule when the repository has one, and a self-review that asks for changes holds the merge until you approve. Someone without write access can still comment, unless the conversation is locked.
Rendered diffs and files
A diff draws a file as what it is where it can, and a file's header names what its lines cannot show. The pull request, commit and compare pages share these views, and the file view draws the same kinds of file.
| File | In a diff | In the file view |
|---|---|---|
| Image (PNG, APNG, JPEG, GIF, WebP, AVIF, BMP, ICO) | 2-up shows Before and After side by side with their pixel and file sizes. Swipe drags a divider across the two. Onion skin fades the new one over the old with a slider. An added or deleted image shows on its own as Added or Deleted. | The picture, with its size. |
| SVG | Rendered (the picture, compared like an image) or Source (the lines). | Image or Code. |
| CSV, TSV | Table or Lines. | Table or Code, with the row and column counts. |
Jupyter notebook (.ipynb) | Cells or Lines. Cells are compared one by one: markdown rendered with the changed words marked, code as a diff, outputs before and after. | Notebook or Code. Markdown is rendered, code colored and outputs shown. |
| JSON, YAML, TOML | Keys or Lines. The changes are listed by key path, ignoring key order and formatting. A file that does not parse shows its lines with the reason. | Code. |
| Markdown, MDX | Rendered or Source, compared section by section with the changed words marked. MDX components show as cards with their props. | Preview or Code. |
package.json, Cargo.toml, pyproject.toml, requirements files and lockfiles such as go.mod, Gemfile.lock and Podfile.lock | The packages added and the versions that moved, not the changed lines. | Code. |
Pick a view in the file's header. Choosing Lines, Source or Code shows the plain text. In the file view, a link to a line, such as #L12, opens the source.
Files that need a careful look
A badge in the file header marks files a reviewer should read with care. The merge checklist lists them too, and only a migration still waits for a person.
| Badge | Files |
|---|---|
| Secrets | .env files other than .env.example, .sample, .template and .dist; .pem, .key, .p12 and .pfx files; SSH private keys; credentials.json |
| CI workflow | .github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml |
| Container | Dockerfiles, Containerfiles and Compose files |
| Code owners | CODEOWNERS, OWNERS |
| Migration | Anything under a migration or migrations folder |
| Infrastructure | Terraform and HCL files, and YAML under k8s, kubernetes, helm, charts or manifests, Chart.yaml and kustomization.yaml |
What lines cannot show
A file header also carries a label for each of these:
- Line breaks changing between LF and CRLF, a byte order mark added or removed, and a missing final newline.
- A file becoming executable or losing it, or another mode change.
- A symlink's target, and a submodule added, moved or removed.
- A file stored in Git LFS. The diff and the file view show the real file, not the pointer, so an LFS image diffs like any other image. A pointer whose file was never uploaded says so.
- UTF-16 and Windows-1252 text, shown decoded in its own charset.
- Files your
.gitattributesmarkslinguist-generatedorlinguist-vendored, labeled Generated or Vendored.
Folded and large files
Lockfiles, generated and vendored files, and files with more than 400 changed lines start folded, with Show it to open one. A binary file reads "Binary file, not shown". A file too large to diff reads "Large file changed, so its lines are not shown here", with Open the file. In the file view, a file over 10 MiB shows its size and a download, plus the first 256 KB of a text file. See Repositories.
Move around the diff
- The Changed files tree lists every file in the diff and filters by name.
- Press
jandkto go to the next and previous file,vto mark the file viewed andwto wrap long lines. The keys work when no text field has focus. Wrap lines is also a button on the file view, and the choice is remembered in your browser.
Suggestions
Put a fenced block labeled suggestion in a comment to propose replacement lines:
```suggestion
let height = tide_height(now);
``` sailfork pr feedback and sailfork brief report the block as the suggested change for that thread, so a person or an agent can apply it.
Threads
A thread is the comments on one line or range. Anyone with push access can resolve it and reopen it.
- In the web app: Resolve and Unresolve under the thread.
- From the CLI:
sailfork pr threads 12 --unresolved
sailfork pr thread resolve t-1a2b -n 12
sailfork pr thread resolve --mine -n 12
sailfork pr thread resolve --all --yes -n 12
sailfork pr thread unresolve t-1a2b -n 12 --mine resolves every unresolved thread whose last comment is yours, which is what you want after pushing fixes. --all resolves every unresolved thread and needs --yes when there is no terminal. --dry-run says what would happen.
When the repository's merge rules ask for it, the pull request cannot merge until every thread on a line of code is resolved. Review text that is not on a line cannot be resolved and does not count.
Review from the CLI
Verdicts and line comments
Flag of sailfork pr review [N] | What it does |
|---|---|
--approve | Approve. |
--request-changes | Ask for changes. Needs --body. |
-b, --body <TEXT>, --body-file <FILE> | The review text. --body-file - reads stdin. |
--inline <PATH:LINE:TEXT> | A comment on a line. LINE is 12 or a range 12-18. Write PATH:LINE@old:TEXT for the old side. Repeat for several. |
Give --inline alone to post line comments with no verdict. If a comment fails, the command stops and says how many posted and that no verdict was recorded.
Comments and replies
sailfork pr comment 12 --body "Rebased on main."
sailfork pr comment 12 --path src/db.rs --line 41 --body "Add an index here."
sailfork pr comment 12 --path src/db.rs --start-line 38 --line 41 --side old --body "Still read here."
sailfork pr comment 12 --reply-to t-1a2b --body "Fixed in the last commit." --path with --line comments on a line of the diff, --start-line starts a range, --side old|new picks the side (default new), and --reply-to <THREAD> answers a thread by the id pr threads prints. --attach <PATH> uploads a file and links it, and images and videos show inline.
Read the open feedback
sailfork pr feedback 12 lists the unresolved threads by file, with the code each one points at and any suggested change. sailfork pr threads 12 lists threads and conversation comments (pr comments is the same command). Both take --json, which is what an agent loop reads.
sailfork pr feedback 12 --json --jq '.threads[] | "\(.path):\(.line) \(.id)"' sailfork wait pr 12 --review blocks until a new review or comment arrives and exits 1 if the review asks for changes.
What a review changes
- Approvals count toward the merge rules. The rules count people other than the author, and each person's latest review is the one that counts. When the rules dismiss stale approvals, an approval from before the latest push no longer counts, and the merge panel says so.
- Changes requested blocks the merge until the reviewer approves. Someone with push access can also choose Dismiss the request in the merge panel. The review goes back to "requested" with the same reviewer. It is refused for the reviewer who asked for the changes, who should review again instead.
- Threads can hold the merge, as above.
The full list of what stops a merge is in Pull requests.
Automated reviews and agent approvals
An agent's approval is shown, but the merge panel does not count it toward the approvals a repository asks for. A person has to approve.
A caisson can also be reviewed adversarially by an agent. The review posts as a comment, never as an approval, and each high or critical finding opens a thread on its line. When the owner's policy requires it, a pull request from a caisson is held until the code carries a review that meets the policy: caisson/c-z4nwicj7 has not been cleared by review. See Caissons and Agents.
What "waiting on you" means
sailfork status has a section named "Waiting for your review". It lists the open pull requests that ask you to review them, up to 50. The other sections are "Your pull requests", with their checks and review state, and "Assigned to you", for issues. Add -R fenil/ocean-landing to see one repository.
sailfork status
sailfork status -R acme/site --json In the web app, a repository's Pull requests page groups open work as Waiting on you and Waiting on others, and its inbox leads with the pull requests you did not open and have not reviewed. Choosing one shows why it needs you, its checks and size, and offers Approve (or Approve and merge when nothing holds it back) and Request changes.
Who can do what
| Action | Who |
|---|---|
| Comment on a line, reply | Anyone who can read the repository, unless the conversation is locked or the owner blocked them. |
| Edit a comment | Its author. |
| Delete or fold a comment | Its author for deleting, and anyone with push access for either. |
| Approve, request changes | Anyone with push access. The author can too, as a self-review that never counts toward approvals. |
| Resolve, unresolve, dismiss a request | Anyone with push access. |
| Ask for a reviewer | The author, and anyone with push access. |
From a script
The review, comment, thread and dismiss routes are in the API reference. The MCP server has the same tools for agents.
Errors people hit
--request-changesneeds--body.pull request ... is already merged: a verdict cannot change a merged pull request.- A write to a locked conversation by someone without write access answers 403.