Reviewing
Reviewing a build
Read a build's screenshot changes, approve or reject them, and see what the decisions mean for the merge.
A build is one upload of screenshots from CI. When it has changes against the baseline, someone looks at each changed screenshot and approves or rejects it. The build's status follows from those decisions. This page covers the build page; Comments and regions covers the discussion beside it.
Anyone who can see the project can approve, reject, comment and ask for reviews: project members, and owners and admins of the workspace. See Members and roles.
Open a build
Section titled “Open a build”Open a project and choose a build from its list, follow the link in a pull request comment or check, or open a review request from Reviews or the Inbox. The page title is the build number (and its name, when it isn't default), with the branch under it.
The header shows the build's state:
| State | Meaning |
|---|---|
| Uploading | CI is still sending files. |
| Processing | The server is comparing. The page updates by itself when processing is done. |
| Needs review | The build finished with changes nobody has decided yet. |
| Approved | Every changed screenshot is approved. |
| Rejected | At least one changed screenshot is rejected. |
| No changes | Nothing differs from the baseline. |
| No baseline | There was nothing to compare with. The first build of a project is like this: every screenshot is new, and later builds are compared with it once it's approved. |
| Failed | The build errored. The message is shown under the header. |
| Expired | Its screenshots were deleted under the project's retention. See Project settings. |
The status, review target and watchers sit on a row of their own under the title. Next to the status the header can show the review target (for example "22h left" or "Overdue 22h"), and an eye with the number of people watching the build: its author and whoever was asked to review, with "you're watching" when you are one of them.
Use the screenshot list
Section titled “Use the screenshot list”The list on the left groups the screenshots in review order. A group is only shown when it has screenshots.
| Group | Starts | Contents |
|---|---|---|
| Couldn't read | open, listed first | Screenshots the server couldn't read (not a valid PNG). They can't be approved, and counts say "N couldn't be read". See below |
| Changed | open | Same name as a baseline screenshot, but different pixels (above the project's diff threshold) |
| Added | open | A screenshot with no baseline |
| Removed | open | A baseline screenshot the build didn't upload |
| Flaky | collapsed | Changed screenshots known to be flaky on the default branch. See Triage and flaky screenshots |
| Unchanged | collapsed | Identical or within the threshold |
A screenshot that couldn't be read has nothing to compare and nothing to decide: the build page shows the file's name and the reason instead of images, and the rest of the build stays reviewable. The build can't pass until it's uploaded again with a valid PNG. What that means for the merge follows the project's Unreviewed changes block merging setting; see How a build flows.
Each row shows a status icon, the name, the number of comment threads, and a short figure: the percentage of pixels that changed, or "resized" when the dimensions differ. Above the list, a counter such as "2 of 5 reviewed" shows how many of the screenshots that need a decision have one. Press j and k to move through the list; a collapsed group counts as one stop, opened with Enter.
Right-click a row for Open, Open in new tab, Copy link, Copy name, Approve, Reject and View baseline. Approve and Reject only appear when the decision isn't already in force.
Look at a change
Section titled “Look at a change”The build page has three compare modes, chosen with the buttons above the image or the keys 1 to 3. A fourth, Design, is on 4 when the project has the Figma integration (see Figma).
| Key | Mode | Shows |
|---|---|---|
| 1 | Side by side | Baseline and new screenshot next to each other |
| 2 | Diff | The changed pixels in red over this build. The This build pill at the bottom right of the image sets how much of the build shows under them: 0% is the changed pixels alone |
| 3 | Slider | A divider you drag between baseline and new screenshot |
Diff and Slider share three controls. [ and ] show less or more of this build, 10% at a time (the new value is announced, "This build 80%"), and holding Option (Option on a Mac) shows this build in full until you let go. The keys work while the pill's slider or the Slider's handle has focus. In Slider they move the divider: this build is on the right, so ] moves it left. Old links to the Overlay mode, which was merged into Diff, open Diff.
Zoom is Fit or 100%, with buttons to step in and out. Fit fills the width of the viewer: a small screenshot is scaled up and a large one down, so a build with a single image fills it too. The View options menu (the ⋯ button) has a Checkerboard background for transparent screenshots, and, for owners and admins, the Dragging draws choice described in Comments and regions. The up and down arrows walk the list. Click an image to enlarge it. The enlarged view steps through the baseline, this build and, in Diff, the changed pixels, in that order.
Decide
Section titled “Decide”-
Pick a changed screenshot in the list and compare it with its baseline.
-
Approve it if the change is intended, or reject it with a reason if it isn't.
-
Repeat until the counter above the list reads "2 of 2 reviewed", or use Approve all when every change is fine.
Decisions are made per screenshot. Each acts at once and shows a toast with Undo.
- Approve (a) approves the screenshot on screen and moves on to the next one that still needs a decision.
- Reject (r) asks for a reason first. The screenshot is marked rejected, which holds back the merge, and it never becomes a baseline. The reason goes to the build's author in their Inbox and to the pull request. A project can make the reason optional; see Project settings.
- Approve all (ShiftA) approves every changed screenshot that has no decision yet. The button carries the count when there is more than one: "Approve all 3".
In the reason field, CommandEnter sends it. Approve and Reject only appear on a finished build with changes. A decision can be changed later: the latest one counts.
How decisions set the build's status
Section titled “How decisions set the build's status”The build's review status is derived from its screenshots: all changed screenshots approved means the build is Approved; one rejected means Rejected; anything else is still Needs review. Unchanged screenshots need no decision. When the status moves, the author is notified, webhooks fire (see Webhooks), and the check on the pull request is updated. People who were asked to review stop being asked once the build is decided.
On the project's default branch, an approved screenshot becomes the baseline later builds are compared with. A default-branch screenshot can become the baseline even while the rest of the build is still pending. Other branches only count once the whole build is approved. See Baselines and ignore regions.
Merge gate
Section titled “Merge gate”With a repository linked, the pull request check follows the build. By default unreviewed changes keep it pending until someone approves; rejected changes fail it. Whether it blocks merging depends on the project's merge gate settings, and whether the repository marks the check as required. See Project settings and GitHub.
Use the sidebar
Section titled “Use the sidebar”Three tabs sit beside the image.
- Details: two groups. Build has the pull request, commit, branch, when it was uploaded, and the baseline it was compared with and how it was chosen ("where this branch started", or the latest build on the default branch when git history wasn't available). People lists everyone who was asked to review and by whom ("Assigned automatically" when a review rule did). Below that: how the selected screenshot changed over recent default-branch builds ("This screenshot on main"), linked issues, and Decisions, every decision made so far with its reason. Identical decisions (the same outcome, person and reason) collapse into one line with a count, such as "Approved by Olivia Owner, 6 times", and By screenshot gives several screenshots decided the same way one line ("Approved 6 of 6 by …").
- Activity: what happened to the build, oldest first: upload, checks, review requests, decisions, comments and issues created.
- Comments: see Comments and regions.
When the baseline is a fallback, a warning banner says which build was used. Fetch more git history in CI (for example fetch-depth: 0 on GitHub Actions) for an exact comparison. See CI examples.
Ask for a review
Section titled “Ask for a review”Request review, in the header, opens a list of the project's members (never yourself). Choosing someone creates an open request, which shows up in their Reviews and Inbox. Asking someone who is already asked does nothing. See Review requests and rules.
If the project has Linear or Jira mapped, Create issue also appears in the header and files an issue for the selected screenshot. See Linear and Jira.
Approve many builds at once
Section titled “Approve many builds at once”On a project's builds list, press x to select builds (or select rows with the checkboxes). A bar at the bottom offers Approve, Reject (with a reason), Request review and Clear selection. This works inside one project; a workspace-wide list can't select builds. The list has filters, grouping and ordering; see Saved views.
Use keyboard shortcuts
Section titled “Use keyboard shortcuts”| Key | Does |
|---|---|
| j / k | Next or previous screenshot |
| a | Approve the screenshot |
| ShiftA | Approve all |
| r | Reject, with a reason |
| c | Write a comment |
| 1 to 3 | Compare mode (4 is Design, with the Figma integration) |
| [ / ] | Show less or more of this build in Diff and Slider |
| CommandEnter | Send a comment or confirm the dialog you are typing in |
| ? | Show every shortcut (the full list is in Keyboard shortcuts) |
Plain keys are switched off while you are typing in a comment field. On a phone the list and the discussion open as sheets from a bar at the bottom, and Approve all, Request review and Copy link sit in its More actions menu.