Review and merge a PR
This guide shows you how to review and merge a pull request.
Open the PR workbench
Section titled “Open the PR workbench”- Navigate to Pull requests in the sidebar
- Select a PR from the list
A PR opens as a tabbed workbench, not a single page. Five tabs open by default, in this order: Overview, Diff, Source control, Chat and Actions (CI checks grouped by workflow). Review — the review pipeline’s progress, then the artefact it published with its findings rail — is deliberately not one of them: a PR has no review until someone asks for one, so Ask AI opens it. A terminal, a single-file editor, an embedded code-server and an in-app browser open on demand; deployment-preview tabs are injected automatically when a preview URL is detected on the PR. Your tab layout is remembered per PR.
The embedded code-server is offered only to the server owner, because it runs on the server as the server’s own user. A session belongs to the device and person that opened it, opens with VS Code’s workspace trust on (VS Code asks before trusting a folder) and runs no task automatically. Everyone else keeps the single-file editor and the file views.
The Overview tab carries the PR’s metadata (author, branch, labels, assignees, reactions, commits, check status) and the action row: refresh, Review, Merge, a button named after your editor (such as Open in VS Code) and a ⋯ overflow menu.
That editor button starts a native editor on the server’s own screen, as the server’s user and outside any sandbox, so it is offered to the server owner only. On a desktop that hosts its own server, that is the person at the desk. The same goes for opening a conversation’s worktree in an editor. Everyone else uses the built-in editor views. Even for the owner, a pull request opens only from a repository linked to the workspace.
Open a PR from a space’s stack
Section titled “Open a PR from a space’s stack”The space’s General → Pull requests section groups linked and branch-matched PRs by repository. When one PR’s base branch is the previous PR’s head branch, they appear in a collapsible stack. Its header identifies the bottom PR, target branch and count; numbered rows run from the bottom PR (1) towards the tip. The numbers describe dependency order, not merge readiness.
Each row shows the title, PR number and state. Hover or focus a row to read its full title and branch names; click or press Enter to open the PR workbench. Focus a stack header and press Enter or Space to collapse or expand it. Unrelated PRs stay separate, and incomplete or ambiguous branch links are not presented as an ordered stack.
In the PR’s header, the stack badge (a layers icon with the number of pull requests in the stack) opens Stacked pull requests, a picker of the stack’s published parts, bottom first. Each entry shows the PR number, part label and position; the checked-out part is marked. Select an entry to open its PR workbench. Publish stack appears only when PR discovery has finished and at least one part has no PR. This also applies to the branch menu. PRs created outside Control Center count as published, too. Partially published stacks offer both actions; single-branch work keeps the individual create/view PR actions.
Commit and push from Source control
Section titled “Commit and push from Source control”A commit you make in the Source control panel is yours: you are its author and committer, under the address your forge verified for your sign-in. When you created a signing key under Verified commits in Settings → You → Commits, the server signs it with your own signing key before it is pushed. A push carries your own sign-in, narrowed to that one repository.
The server runs Git on its own machine, in a tree an agent or a pull request can change, so it runs none of the programs a repository can choose:
- Commits skip the repository’s Git hooks, as
git commit --no-verifydoes. A pre-commit hook, a commit-msg hook or a pre-push hook does not run - Credential helpers, editors, external diff tools and signing programs that the repository configures are ignored
Run your checks yourself before committing, or in CI.
Changing the code needs the write grant on the repository: saving or reverting files in the editor, Pull latest PR commits, committing and pushing, publishing a branch, and the stack actions that cut, check out or publish a part. With only read or review access you see the files and diffs, and these actions answer “You can read this repository but not change it. A workspace admin can grant write access.”
Pull latest PR commits brings the review worktree up to the pull request’s newest commits. It fetches with your own GitHub sign-in, and asks you to sign in when you have none. Commit or discard your changes first: a worktree with uncommitted changes is not synced.
Read the diff
Section titled “Read the diff”Open the Diff tab to see the whole PR diff at once, with a file tree for jumping between files.
- The settings button in the diff toolbar switches split (side-by-side) and unified view and toggles line wrapping and code-font ligatures.
@@hunk headers are replaced by Show N lines / Show end of file affordances that splice in the surrounding context on click.- Press
j/kto step between files,cto collapse or expand the focused file,tto return the sidebar to the file tree and⌘Fto search across the whole diff (Enter/Shift+Enterwalk the matches). - Press
vto mark the focused file as viewed, and the cursor advances to the next file. On GitHub the viewed state is stored on the forge, so it follows you between clients; GitLab and Bitbucket have no such API, so there it is remembered on this device only.
Mouse-drag in the code area selects text down to the exact column and ⌘C
copies the raw source rather than the rendered diff markers.
Leave inline comments
Section titled “Leave inline comments”- Tap a code row’s gutter to open a composer anchored to that line, or use the
+button on a file header for a file-level comment - Write your feedback in Markdown
- Submit
On GitHub and GitLab the composer offers two submits: Add single comment posts immediately, and Start a review / Add to review queues the comment onto a pending review that goes out with Approve, Request changes or Comment. Bitbucket has no pending-review batching, so there every submit posts immediately. An immediate post shows a pending state until the forge confirms it, then flips to synced. If the post fails, the thread is marked with the error and offers a retry.
Only the review body is a draft: it is saved server-side against (owner, repo, PR number) a moment after you stop typing, so it survives a reload and follows you between the desktop and web clients.
Submit a review
Section titled “Submit a review”- Press Review in the Overview action row (it is hidden on your own PRs and on a closed or merged PR)
- Write the review body. You can attach an image, insert an emoji or a GIF and toggle between write and preview
- Press Request changes, Comment or Approve
The verdict is the button — there is no separate verdict picker. After Approve or Request changes, the button relabels itself to Approved or Requested changes and the draft body is cleared. A Comment verdict leaves the button labelled Review.
The Merge button appears when you have write access and the PR is open and not a draft. Its colour is a readiness signal derived from required approvals and check state (ready / pending / blocked) — it is advisory only. The button is never disabled by review state; the forge’s own branch protection is what enforces the rules.
- Press Merge to open the merge flyout
- Pick a merge method: squash, merge commit or rebase (squash is the default). Bitbucket has no true rebase merge, so rebase maps to its fast-forward strategy and fails on a diverged branch
- For squash and merge commit, edit the prefilled commit title and description. Rebase takes neither and hides both fields
- Read the warnings panel — it names failing checks and pending reviews, but does not block you
- Press the merge button in the flyout to confirm
Merging is irreversible: it pushes commits to the forge, so it gets a confirmation
step instead of an undo entry. Afterwards the PR’s cache is invalidated, its status
flips to Merged and a PullRequestStatusChanged event fires with status
merged. That event releases the ephemeral worktree the editor button opened and starts
two seeded pipelines: Stale repository cleanup, which removes the PR’s stale
worktrees and conversation folders and Release notes, which drafts a changelog
entry.
Hand the PR to reviewer agents
Section titled “Hand the PR to reviewer agents”The ⋯ overflow menu on the Overview tab carries Ask AI, which starts the
seeded pr_review pipeline for this PR. It only appears while the PR is open. See
Use AI-powered review for what the pipeline does and
how to publish its findings, and Review compute
for the deterministic cohort and axis model.
Review an external PR
Section titled “Review an external PR”Control Center also imports PRs opened by humans outside the app. The review flow above is identical. External PRs are detected by the PR polling service.
Troubleshooting
Section titled “Troubleshooting”My pre-commit hook didn’t run
Section titled “My pre-commit hook didn’t run”Commits made in the app’s Source control panel skip the repository’s Git
hooks, as git commit --no-verify does. The server runs Git on its own
machine, in a tree that agents and pull requests can change, so it never runs a
program the repository chooses. Run the hook’s checks yourself, or rely on CI.