How to approve visual changes in a Chromatic pull request

To approve a visual change in Chromatic, open the build linked from your pull request, inspect each changed story snapshot, and accept only the changes you intend. Acceptance updates the snapshot baseline. If a change is a regression, deny it; that marks it denied and fails the build. For team sign-off, use the pull request’s separate UI Review workflow and approve the review after its changes, discussions, and assigned reviewer approvals are complete.

These actions answer different questions: accepting a snapshot decides what Chromatic should compare against next time; approving a UI Review records stakeholder sign-off; a required Git provider check determines whether the result gates merging. See Chromatic’s [In pull request workflow](https://www.chromatic.com/docs/in-pull-request/) and [Review](https://www.chromatic.com/docs/review/) documentation.

1. Accept or deny changed snapshots

Open the Chromatic build linked from the pull request. Find the stories marked as having visual changes.
Inspect each changed snapshot and its diff against the accepted baseline. Check the relevant context and states, not just whether the difference looks small.
For an intentional change, accept the snapshot. This updates the baseline that future builds use for comparison. Chromatic’s documentation says: “If the changes are intentional, press the accept button to update the baselines.” (Chromatic, In pull request workflow.)
For an unwanted change, deny it. The change is marked denied and the build fails, so fix the code and run a new build.
Review the resulting build status. Once all changes are accepted, the build passes.

Accepting a snapshot does not, by itself, mean the team approved the pull request. It changes the visual reference. Use UI Review when you need review discussions and reviewer sign-off.

2. Approve the pull request’s UI Review

A UI Review is Chromatic’s stakeholder review flow for the visual changes a branch would introduce relative to its base branch. Its Changeset focuses reviewers on that comparison. Follow the review’s checklist:

Open the UI Review attached to the pull or merge request and inspect its Changeset, which compares the head branch with the base branch.
Assign reviewers from the Review Activity screen if needed. Assigned reviewers receive an email link. A project can also have default reviewers configured on its Manage page; assigned default reviewers must approve for the Review to pass.
Leave questions or change requests as discussions on the relevant visual change. Resolve each discussion after the requested work is addressed.
Approve the Review once the Changeset is approved, discussions are resolved, and assigned reviewers have approved as required by the checklist.

Chromatic describes UI Tests and UI Review as distinct workflows: tests detect visual or interaction issues, while Review helps stakeholders align on intended changes. See the official Review documentation.

3. Require the appropriate pull request check

Chromatic can report UI Tests and UI Review status to a linked Git provider. To gate merges, configure the appropriate status check as required in your provider’s branch protection or merge-check settings:

Require UI Tests when the gate should depend on the test/build status.
Require UI Review when the gate should include stakeholder feedback and sign-off.

A required check only works when Chromatic and CI actually report a result. If a check stays pending, verify that the relevant project setting is enabled and that the CI step which reports it runs for the pull request. Chromatic documents indefinitely pending states when a required check is disabled in project settings or its CI step never runs. See Mandatory PR checks.

Also inspect how the workflow handles skipped builds. A build run with --skip is marked skipped and passes immediately, even if the commit has visual changes. Decide whether that behavior fits your merge policy.

4. Understand automatic and manual reviews

With a linked GitHub, GitLab, or Bitbucket integration, Chromatic can trigger UI Reviews for pull or merge requests. One documented exception is GitHub Enterprise Server: opening a PR does not trigger the Review, though a Review is created when a build runs on the PR branch. Check the automatic UI Review FAQ for current integration behavior.

You can also create a UI Review manually to compare branches, as long as each branch has a build. A manually created review does not automatically create a Git provider status check. Chromatic documents a custom webhook as a possible way to create one. Details are in Manual UI Review.

5. Check what a green CI result means

A green job is not always proof that a person reviewed the snapshots. Chromatic’s GitHub Actions options can change the meaning of a successful exit:

exitZeroOnChanges can let the action exit successfully when changes are found without accepting those changes.
autoAcceptChanges accepts detected changes, updating the baseline without a human making that decision in the review flow.

Read your workflow configuration before treating a passing action as snapshot acceptance or human sign-off. Chromatic recommends running its step on push events and describes possible unexpected baseline behavior with GitHub’s pull_request event in some configurations. See GitHub Actions and CI.

Snapshot acceptance, UI Review, and required checks

Action or status	What it answers	Effect
Accept a changed snapshot	Should this image become the new visual reference?	Updates the baseline.
Deny a changed snapshot	Is this visual change a regression?	Marks it denied and fails the build.
Approve UI Review	Have stakeholders reviewed and signed off on the proposed changes?	Completes the Review checklist when its requirements are met.
Require a provider check	Should this status be a merge gate?	Blocks merging according to the provider’s policy while the required check has not passed.

Troubleshooting

The UI Review check remains pending

Cause: The check may be required but disabled in the Chromatic project, or the CI step that reports it did not run. Fix: Confirm the project setting, ensure the correct CI event and job execute for the pull request, then check that the provider integration is linked. Start with Chromatic’s mandatory-check guidance.

The build fails after a visual change

Cause: A change was denied or remains unaccepted under the project’s workflow. Fix: Inspect the diffs. If the change is intended, accept it; if it is a regression, fix the UI and run a new build. Do not accept a change just to clear the failure.

The action is green, but changed snapshots still appear

Cause: The workflow may use exitZeroOnChanges, which can return success despite detected changes, or may otherwise be configured so that green status does not represent human review. Fix: inspect the Chromatic action inputs and the build’s snapshot status. Keep snapshot acceptance, UI Review approval, and CI success as separate checks in your release process.

Changes were accepted without the expected reviewer decision

Cause: autoAcceptChanges may be enabled, or the action may run under an event configuration with unexpected baseline behavior. Fix: review the GitHub Actions configuration and event type, then confirm the baseline history and project settings. Consult the GitHub Actions guide.

A skipped build passes a required check

Cause: Chromatic documents that a build invoked with --skip is marked skipped and passes immediately, even when visual changes exist. Fix: review why the job skips and whether your branch protection policy should allow that path.

No UI Review appears when the PR opens

Cause: The provider may not be linked, automatic review settings may be off, or the integration may follow an exception such as GitHub Enterprise Server’s documented behavior. Fix: confirm integration and project settings; ensure a build runs on the PR branch. If appropriate, create a manual review, keeping in mind that it does not automatically create a provider status check.

Reliability and workflow notes

Make the merge gate explicit. A team sign-off requirement should use the UI Review status; a test gate should use UI Tests. Configure the desired check in the Git provider.
Keep automation’s meaning visible. Document whether CI accepts snapshots automatically, exits successfully when changes exist, or skips builds. A green job alone can be ambiguous.
Account for integration paths. Automatic review creation, manually created reviews, skipped builds, and provider status reporting behave differently. Validate the paths your repository actually uses.
Cost and performance. The workflow described here is about Chromatic snapshots, review and CI configuration. The cited documentation does not establish a cost or timing figure for this approval process; check your project’s current plan and usage information rather than relying on an assumed rate.

Or skip the browser setup

For capturing a page screenshot separately from Chromatic’s snapshot approval workflow, ScreenshotNeo is a website screenshot API and MCP server. Make one GET request with a URL to receive a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing. Response headers report the page verdict and billing status.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
1,000 screenshots a month are free with no card. Paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Does accepting a snapshot approve the pull request?

No. It updates Chromatic’s visual baseline. Team sign-off is handled by UI Review, and merge gating is configured through the provider’s required checks.

Can I review branches without a connected Git provider?

Yes. A manual UI Review can compare branches if both have builds, but it does not automatically create a provider status check.

Which check should I require for design sign-off?

Require UI Review for reviewer feedback and approval. Require UI Tests for the test/build status. Some teams may require both to meet their merge policy.