AI visual review in CI: hold the merge on real regressions

AI visual review in CI is a check that screenshots your UI on every pull request and uses a model to decide whether each visual change is an intended change or a regression, then holds the merge when it finds a regression. It runs in the same pipeline as your unit and end-to-end tests, on the same trigger, and it reports the same way they do: a status check that is green when the UI is intact and red when something moved that should not have.

The review has three moving parts wired into your continuous integration pipeline. First, capture: on each pull request the pipeline renders your UI and takes a screenshot of every component or page state. Second, diff: each screenshot is compared pixel by pixel against a committed baseline, so a run that changed nothing produces no diffs. Third, the judge: for every changed screenshot, a vision model looks at the before and after and labels it a regression or an intended change, with a short reason. The verdict feeds a required status check, so a regression blocks the merge the same way a failing test does. The model is the part that separates this from plain pixel diffing, and how the verdict is produced is covered in the AI judge.

Your test suite does not look at your UI. Unit tests assert on functions and rendered text, end-to-end tests click through flows and check that elements exist and respond, and both can pass in full while the page they exercised is visibly broken. A button can render, be clickable, and fire the right handler while sitting on top of the heading it was supposed to sit beside. A test that asserts the button exists goes green. The layout regression ships.

The mechanism is that most visual breakage lives in state your assertions never read: a changed CSS token that drops contrast below legible, a flex container that wraps one item too early at a common width, a shared component whose padding was nudged and now shifts every page that imports it, a z-index that lets a modal slide behind its backdrop. None of that changes the DOM in a way a selector-based test notices. The pixels change; the assertions do not. So the pull request collects a wall of green checks, a human merges on the strength of them, and the first report of the broken layout comes from a person looking at the running app after release.

AI visual review closes that gap because it reviews the one artifact the rest of CI ignores: the rendered pixels. It does not need to know which flex rule wrapped or which token dropped. It sees that the header now overlaps the button and calls it a regression, before the merge, not after the release.

It slots in as one more job on the pull request, alongside the jobs you already run, and it reports through the same status-check mechanism your branch protection already understands. The flow is linear:

1. Capture on the pull request. The pipeline renders your UI and screenshots every state it covers - each Storybook story, each page, each declared mode - on the branch's commit.
2. Diff against the baseline. Each screenshot is compared to the baseline committed for that state. Unchanged states produce nothing to review; only what moved goes forward.
3. AI judge verdict. For every changed screenshot the model labels the change a regression or an intended change and records a reason, working from a before/after cropped to the region that actually moved.
4. Required status check. The verdicts roll up into a single check. A regression makes it red and blocks the merge; accepting an intended change promotes it to the new baseline and flips the check green, with no CI re-run.

The last step is what makes it a gate rather than a report. A check that only annotates a pull request is advisory, and advice gets merged past on a busy day. Marking the check required in branch protection is what turns the verdict into a merge condition, and the mechanics of that - including why accepting flips the check live - are in make the visual check required.

A pixel diff can only tell you that something changed, never whether the change is wanted. Restyle a card on purpose and a raw diff flags every screenshot that card appears in, exactly as loudly as it flags a real regression. So a diff-only tool hands you a queue: every changed screenshot, undifferentiated, waiting for a human to open each one and decide intended or broken. That queue was tolerable when a team opened a handful of UI pull requests a week. It stops being tolerable when coding agents open them, because agents produce visual changes far faster than a person can sit and adjudicate them one by one, and someone still has to look at every diff.

The AI judge does the first pass of that adjudication in the pipeline. It splits the changed screenshots into the intended changes, which it explains and stages for a one-click accept, and the regressions, which it explains and blocks on. A human is no longer the throughput limit on review; they confirm a judgment the model already made, or overturn it on the rare miss. The volume that breaks a manual triage queue is precisely the volume a per-change verdict is built to absorb.

The gate earns its keep when an agent opened the pull request, because an agent cannot see what it changed. It edits the CSS, the page renders, it reports success, and it has no picture of the result to check itself against. The required status check is the backstop for exactly that: the break the author could not see still holds the merge. Nothing about the gate changes when the author is a machine instead of a person, which is the point - it is the same merge condition either way.

There is a second, faster path for an agent that I am keeping separate on purpose, because it is its own subject rather than part of the gate. The same per-story verdict is also exposed over the Model Context Protocol, so the agent that wrote the change can pull each diff, read the judge's call, and fix a regression before the required check even runs. That agent-side loop, tool by tool, is in visual testing MCP: let your agent triage the diffs, and the triage visual changes skill packages it into one command. However far you take that, the gate stays put behind it, catching whatever slips through.

So the whole thing reduces to one change to your pipeline. Add the capture-diff-judge job to the pull request, mark its status check required in branch protection, and the green check stops meaning the unit tests passed and starts meaning the rendered UI is intact. A regression holds the merge; an intended change is one click from becoming the new baseline. The wall of green over a broken layout that this started with is precisely the failure that gate exists to end.