Skip to content

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.

CirCI
Build #93 with one changed screenshot, pricing, shown side by side with its baseline. The header has the Needs review status, the overdue time and the watchers, with Request review, Reject, Approve and Approve all on the right. The Details tab lists the build and the people asked.
A build with one changed screenshot. The list is on the left, the viewer in the middle and the Details tab on the right.

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 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.

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.

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.

  1. Pick a changed screenshot in the list and compare it with its baseline.

  2. Approve it if the change is intended, or reject it with a reason if it isn't.

  3. 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.

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.

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.

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.

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.

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.

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.