How to approve visual changes in an Argos CI pull request

To approve visual changes in an Argos CI pull request, open the Argos build linked from the pull request, compare each changed snapshot with its baseline and diff, and approve only when the visual change matches the pull request’s intended change. You can record the decision in Argos’s browser review or, after inspecting the build data, with the Argos CLI.

A green or completed build label alone is not enough evidence. Review the changed screenshots, use the pull request title, description, linked issue, and code changes to understand what was intended, and reject or request changes when a difference is unexpected or potentially flaky. Argos documents that one rejection blocks a build; with no rejection, one approval passes it. Argos review documentation

Review and approve in the browser

Open the build for the pull request. Follow the Argos status check or bot comment associated with the pull request. Confirm you are reviewing the build for the relevant commit.
Inspect every changed snapshot. Compare the current screenshot with its baseline and inspect the diff mask. Use the split or single view, changes overlay, and highlighter to understand the location and extent of the change.
Move through the changes and inspect details. The review page supports J and K to move between changes. Zoom and pan stay synchronized between panes. Check the page’s keyboard shortcut list; it documents Y to accept, N to reject, and Enter to open the review popover.
Check the pull request’s intent. Read its title and description, follow linked issues, and inspect relevant code changes. Ask whether the screenshot difference is the expected result of that work. If context is missing, ask the author for it before approving.
Record the decision. Approve if the visual change is intentional and correct. Otherwise reject or request changes and identify the affected snapshot. Add a concise Markdown summary to explain the decision. Argos retains review history, including who decided and when.

What to look for in the comparison

Baseline: Verify which prior image Argos used as the comparison point.
Current image: Check the rendered page in the pull request build, not a local screenshot or an image from another commit.
Diff mask: Locate changed pixels and determine whether they correspond to the intended code change.
Surrounding page: Look for unintended layout shifts, missing content, clipping, or changes outside the intended component.
Pull request context: Tie each material visual change to the described requirement or issue.

Approve or reject from the CLI

The CLI is useful when you want to inspect build and pending-snapshot data from a terminal, or record a review as part of a script or agent-assisted workflow. Structured output helps identify what needs review; it does not replace visual inspection or the check against pull request intent.

Install and inspect the build

npm install -D @argos-ci/cli

# Inspect build details
npx argos build get <build>

# List only snapshots waiting for review
npx argos build snapshots <build> --needs-review --json

Replace <build> with the build identifier associated with the pull request. Inspect the snapshots and their visual evidence in Argos before submitting a decision.

Submit the decision

# Approve after verifying the visual changes
npx argos review create <build> --event approve --body "Visual changes match the pull request intent."

# Reject when a snapshot has an unexpected change
npx argos review create <build> --event reject --body "Unexpected layout shift in the checkout snapshot."

The CLI review feature was announced in the Argos changelog on April 20, 2026. Check the official changelog and current CLI documentation for current command behavior and options.

CLI authentication

Argos documents different token requirements for reading build data and submitting a review: build reads use the project token, while submitting a CLI review requires a personal access token and respects the user’s existing project permissions. For automation, follow Argos’s environment-variable or GitHub OIDC guidance. The official AI review guide advises against running the interactive login command in CI. Do not put a personal token in a checked-in file or print it in CI logs. See the Argos CLI documentation and AI review guide.

How Argos review decisions affect the pull request

Each reviewer’s verdict counts independently. Argos says one rejection blocks a build; when nobody rejects it, one approval passes it. The resulting status can appear as a pull request check and may be required by branch protection. An approval is therefore a consequential review decision: verify the snapshots before recording it. Argos review documentation

Argos selects a comparison baseline from Git history. Its Diff documentation describes a pull request baseline as the latest approved build on the commit where the branch diverged from its base branch, the merge base. Auto-approved branches such as main can keep that reference current. When a comparison looks surprising, check the baseline identified for that build instead of assuming a code change or screenshot from another commit explains it. Argos Diff documentation

A reliable review checklist

Open the build associated with the pull request and confirm the relevant commit.
Review changed snapshots against the displayed baseline and diff.
Use the pull request description, linked issue, and relevant code to establish intent.
Approve only changes that match that intent.
Reject or request changes for unexpected or unresolved flaky differences, naming the affected snapshot.
Include a short rationale so the author and later reviewers understand the decision.

Troubleshooting

The CLI cannot find the build

Make sure you copied the build identifier from the correct Argos pull request build and pass it in place of <build>. Check that the CLI is using the project token for build reads and that the token can access the project.

Build inspection works, but submitting a review fails

Reading build data and creating a review use different documented token requirements. Configure a personal access token for the review command and verify that the account has permission to review in the project. A project token alone is not the documented credential for submitting the CLI review.

The snapshot list is empty

The --needs-review filter lists snapshots awaiting a decision. An empty result can mean none are pending, or that the build identifier is wrong. Inspect the build with argos build get and confirm that you are looking at the pull request build you intended to review.

The diff appears unrelated to the pull request

Check the actual baseline and current image shown for the build. The baseline is selected from Git history at the branch’s merge base, using the latest approved build on that commit. Confirm the pull request branch and base branch, then inspect the changed snapshot and related code before deciding.

A difference looks flaky or cannot be explained

Do not approve an unresolved difference. Identify the snapshot and explain what looks unexpected, then ask for the flake to be investigated or resolved. Argos’s review guidance says to explain problematic snapshots and not recommend approval until a flake is resolved.

Use the documented environment-variable or GitHub OIDC setup for CI instead of running the interactive login flow in a job. Keep credentials in the CI secret store and restrict them to the access the workflow needs. Consult Argos’s AI review guide for its current guidance.

Performance, reliability, and review cost

The main time cost is examining the changed snapshots and establishing their intent. The CLI’s pending-only snapshot filter can reduce the amount of build data you need to inspect, while the browser’s synchronized panes, overlay, and keyboard navigation help move through visual changes. Neither interface makes an unexplained difference safe to approve.

For reliable pull request decisions, retain enough context for reviewers to connect snapshots to the intended work. A useful review comment names the snapshot and describes whether its change is expected. In CI, keep authentication non-interactive and verify that the credential matches the operation: project token for build reads, personal access token for submitting a review. Argos’s cited materials do not provide a topic-specific monetary cost or review-time benchmark, so no cost or speed figure is assumed here.

Or skip the browser setup

If your task is to capture a page for a visual check or a review artifact, ScreenshotNeo is a website screenshot API and MCP server for developers. It does not approve Argos snapshots or replace reviewing the Argos baseline and pull request. It can provide a screenshot with one API request:

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

See the ScreenshotNeo API documentation for options and setup. ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Is there an Argos command that approves every snapshot in a pull request?

The documented CLI command creates a review event for a build. The review guidance is to inspect the changed snapshots and decide based on the pull request’s intent; do not approve changes you have not verified.

Does one approval always pass an Argos build?

According to Argos, one approval passes when there is no rejection. A single rejection blocks the build, so reviewers’ decisions are consequential independently.

Can I review with only a project token?

Argos documents project-token access for build reads and a personal access token for submitting a CLI review. The credentials serve different operations.

Can a screenshot capture service approve an Argos visual review?

No. A capture service can produce an image, but approval requires comparing the Argos snapshot with its baseline and judging it against the pull request’s intended change.