Docs
Docs menu

Reviewing and merging

Comment on changes and lines, suggest changes, submit reviews, approve a revision, merge it, and set a repository's merge rules and protected branches.

Every change, whether an agent’s or a person’s, goes through the same review: people discuss it, someone with write access approves its latest revision, and it’s merged once the repository’s merge rules are met.

Reading the diff#

A change’s diff shows each changed file with its added and removed lines, side by side (Split) or one after the other (Unified). A diff with many files, or a very large file, starts folded: List the files shows each file with its line counts, and a click opens that file. Expand all and Collapse all open or fold every file, and a file’s name folds it. A file with comments on its lines, or a link to its lines, stays open.

Comments and threads#

The Conversation on a change page is for comments on the change as a whole. Comments are Markdown; Preview shows how one will look before you post it. Each comment starts a thread that others can Reply to. Mark a thread Resolve once it’s dealt with, and Unresolve to open it again. Resolved threads fold up.

Comments are signed and stored in the repository with the change, so they move with it to another node.

Comment on lines#

To comment on specific lines of the diff, hover over a line and press the + beside it. Drag, or shift-click another line, to cover several lines. Write the comment, then either:

  • click Add single comment to post it now. The thread appears under those lines.
  • click Start a review to keep it in a pending review, and post it later with your other comments. See Reviews.

On lines of the new version, the composer also offers Suggest a change: see Suggest a change.

A thread is written on one revision, but it follows the lines into later revisions. When a later revision changes those lines, the thread says “the lines changed since”, and links to the revision it was written on. Threads whose lines are gone are listed under On earlier revisions.

Who can comment#

On Settings → Comments, a repository admin chooses Who can comment:

  • Everyone who can read: anyone with read access, once signed in. For a public repository, that’s anyone signed in to the node.
  • Writers only: only people with write access can open threads and reply. Everyone who can read still sees the conversation.

Suggest a change#

When the fix is a few lines, write the lines instead of describing them. Select lines on the new side of the diff as for a line comment, and click Suggest a change in the composer. A Suggested lines box opens, filled with the lines you picked. Edit them into what they should be: they replace the picked lines as a whole, and an empty box deletes them. Remove suggestion turns it back into a plain comment.

The comment text is optional when there’s a suggestion. Post it with Add single comment, or add it to a review with Start a review.

Suggestions only work on the new side. On lines of the old version, before the change, you can comment but not suggest.

In the thread, the suggestion shows as a small diff under the heading Suggested change: the lines it removes and the lines it adds.

Apply suggestions#

People with write access to the repository see Apply suggestion under each suggestion they can apply. To apply several at once, click Add to batch on each. A bar at the bottom of the page counts them (for example “3 suggestions in the batch”); click Apply 3 suggestions, or Clear to empty the batch.

Applying makes a new commit on top of the change’s latest revision, and records it as the next revision: applying to r2 makes r3. Nobody’s commit is rewritten.

  • The commit’s author is you. The node is the committer.
  • The message is “Apply suggestion from mira” for one suggestion, “Apply suggestions from mira” for several by one person, or “Apply suggestions from review” for several people.
  • Each suggester other than you gets a Co-authored-by: line.
  • If the change tracks a branch (it was proposed from one), the branch moves to the new commit too. Pull before you go on working on it.

Each applied thread is resolved and says Applied in r3 by and who applied it. Like any new revision, r3 needs approving before it can be merged.

Agents can’t apply suggestions. When an agent revises a change, it sees the open suggestions and applies the ones it agrees with in its own revision.

When applying is refused#

Apply suggestion doesn’t show, or the node refuses with a message saying why, when:

  • the change has been merged or closed;
  • the change was opened as a pull request on GitHub: apply suggestions there;
  • the change tracks a protected branch, which only merging moves;
  • the tracked branch no longer points at the change’s latest revision (“isn’t at r2; push or pull first”);
  • the suggestion is outdated: the lines it replaces changed in a later revision. It says “Lines changed since r1”, with a link to the revision it was written on;
  • the lines already read as the suggestion says;
  • two suggestions in the batch change the same lines of a file.

Nothing is written when applying is refused.

Reviews#

A review gathers your comments, replies and suggestions on a change and sends them together, with a summary and an outcome. The author gets one notification for the whole review instead of one per comment.

Gather comments#

In any comment composer on the change page (on lines, in the Conversation, or a reply), click Start a review instead of posting. The comment is kept as pending. After the first one, the button reads Add to review with the count, and ⌘/Ctrl+Enter adds to the review instead of sending.

Pending comments show where they’ll go, dashed and marked Pending, “sent when you finish your review”. Edit and Remove change them. Nobody else sees them: a pending review is kept in your browser only, not on the node, so it doesn’t follow you to another device.

A pending review belongs to one revision, the one its first line comment is on. To comment on the lines of another revision, submit or discard the pending review first.

Finish a review#

While a review is pending, a bar at the bottom of the change page shows Pending, “Review: 3 comments on r2”, and Finish review. Click it to open Finish your review of r2. The dialog lists the pending comments (each can be removed), and takes:

  • the outcome: Comment, Approve or Request changes;
  • an optional summary, in Markdown.

Click Submit review to send it. Discard review throws the pending comments away.

The outcomes:

  • Comment: feedback, with no decision.
  • Approve: approves the change as well, as Approve r2 would. It’s offered only to people with write access, on an open change, when the review is of the latest revision. On an older revision the dialog says “Approving is for the latest revision”.
  • Request changes: asks the author for changes. It doesn’t block merging; it puts the change under Changes requested in the author’s Inbox until that reviewer approves or a new revision arrives.

An approving review must be of the latest revision. If a new revision arrived after you loaded the page, the node refuses it: reload and review the new revision. If the new revision arrives just as the review is being saved, the review is posted without the approval, and the page says “Review submitted, but not approved”. Approve the new revision once you’ve looked at it.

Reviewers and review cards#

At the top of the change page, under its title, Reviews lists everyone who reviewed the change, with where each one stands: approved, requested changes, or commented. A later comment review doesn’t replace an earlier approval or request for changes. “on r1” marks a review of an older revision. Click a name to go to that review.

Each review shows in the Conversation as a card: who reviewed which revision, the outcome, the summary, and a link to each comment, suggestion and reply it added.

Reviewer agents submit reviews too, with Comment or Request changes. They can’t approve.

Approve#

People with write access see Approve r2 (with the latest revision’s number) at the top of the change page. Approving records a signed status change on the change. A review submitted with the outcome Approve does the same (see Finish a review).

An approval is for one revision. When a new revision arrives, the change needs approving again before it can be merged. Agents can’t approve anything: only a person’s approval counts.

Merge#

Once the merge rules are met, click Merge r2. If they aren’t, the button stays disabled and the reason shows next to it, such as “Approve r2 to merge it”.

Merging puts the revision on its target branch:

  • If the revision already sits on the branch’s tip, the branch moves forward to it.
  • Otherwise the node rebases the revision onto the tip. The rebased commit carries the change ID in a change-id header.
  • If the rebase conflicts, nothing moves and the change becomes Conflicted, with the files that conflict. Rebase your branch onto the target and push again: that’s a new revision, which needs approving again.

For a repository that follows GitHub, the button says Open a pull request for r2 (or Push r2 to GitHub) instead, and the change is merged on GitHub (see GitHub).

Merge rules#

The Merge policy box at the bottom of the change’s Evidence panel shows each rule and whether the latest revision meets it.

  1. Human approval of the latest revision. The latest status is an approval, given after the latest revision arrived, by a person who has write access to the repository now. An approval by someone who has since lost write access doesn’t count.
  2. A valid attestation, including the runner’s claim. The node’s attestation for the latest revision verifies, its signer is trusted, and for an agent’s run, the runner’s own signed claim checks out. See Provenance.
  3. Ran pinned, only if the repository requires it: the agent’s run used an image pinned by digest and a pinned Claude Code version.
  4. Required CI jobs, only if the repository requires some: each passed on the latest revision, in every matrix combination, on the runner of someone with write access. See Required jobs.

The box also shows whether every revision has a valid attestation. That’s for your information; only the latest revision’s is required.

Approval from someone other than the author#

By default, the author of a change may approve it. That suits a repository one person works on. When more people work on it, a repository admin can tick Approval from someone other than the author under Settings → Merging. A person’s own proposal then needs another person’s approval before it can be merged.

Require pinned runs#

To merge agents’ changes only from runs with a pinned Claude Code version, a node admin runs:

moru-node repo-policy acme/timetable --require-pinned true

Run it without --require-pinned to see the current setting. It takes effect at once, with no restart. It applies to agents’ runs only, not to changes people push. Pinning itself is set on the node’s profiles: see Agent profiles.

Protected branches#

A protected branch moves only when a reviewed change is merged into it. git refuses a push that moves or deletes it, with a message such as:

main is protected: push another branch and propose it, or push to refs/for/main

Creating a protected branch that doesn’t exist yet is allowed, so a new repository can take its first push. Admins aren’t exempt, but they can change the setting.

On Settings → Merging, under Protected branches, a repository admin types a branch name and clicks Protect, or removes one with its ×. Names match exactly. With no protected branches the page warns that anyone with write can push straight to any branch, skipping review.

  • New repositories protect the first branch pushed to them, whatever it’s called. A repository created with a README protects main at once.
  • Repositories that follow GitHub start without protection, since their branches come from GitHub. Unlinking one offers to protect its default branch.

Protected branches, the approval rule and who can comment are part of the repository’s signed access record, so they move with the repository to another node.

Command menu
Search for a page, repository, change or request, or run a command