Skip to content

Introduction

FAQ

Short answers to the questions people ask first, each with the page that has the details.

Your own tests do. CirCI compares and reviews screenshots; it doesn't capture them. circi upload <dir> uploads every *.png under a folder, so any tool that writes PNG files works. The Vitest plugin captures them from Vitest's browser mode, and the Argos SDKs work by changing two variables. See The CLI.

PNG only. A file that isn't a valid PNG is marked "Couldn't read" and can't be approved, and the Argos-compatible API refuses JPEG. A single file may be up to 25 MiB.

The CLI reads the commit, branch, pull request and base branch from GitHub Actions, GitLab CI, Bitbucket Pipelines, Gitea and Forgejo Actions, CircleCI, Buildkite, Jenkins and Azure Pipelines. On any other system, or to override what's detected, pass the values as flags. See CI examples.

No. A screenshot is a file with a name, and the browser, viewport and test are optional metadata that can travel with it in a <file>.png.json sidecar. To keep several browsers apart, upload one build per browser with --name: each name has its own baselines. See Vitest.

I have a monorepo or several apps. How do I set it up?

Section titled “I have a monorepo or several apps. How do I set it up?”

Make one project per thing you test. Each has its own CI token, baselines, rules and settings, and one workspace holds them all. Within a project, use --name to separate builds of the same commit (a mobile build and a desktop one, say). See Several builds per commit.

Yes for the upload side: the Argos SDKs upload to CirCI when ARGOS_API_BASE_URL and ARGOS_TOKEN point at it. Old builds aren't imported, so the first approved build on your default branch becomes the baseline. It's built from the SDKs' source and has not been verified against the real SDKs. See Argos-compatible API.

Why is every screenshot "Added" on my first build?

Section titled “Why is every screenshot "Added" on my first build?”

A project's first build has nothing to compare with, so all its screenshots are added and need review, even on the default branch. It's never approved automatically. Approve it once and later builds compare against it. See How a build flows.

For a pull request it walks the history from the merge base with the base branch. For a default-branch build it walks from the commit before. If the history isn't available it falls back to the newest eligible build on the default branch, and the build page says which source it used. See Baselines and ignore regions.

Any workspace member who can see the project. Changing settings, rules, tokens and integrations needs an owner or an admin. See Members and roles.

It can. By default, unreviewed changes keep the check red. With a linked repository the git host's check is the gate and you mark it required in branch protection; otherwise circi upload --wait is, and it exits 1. Each project can turn this off. See How a build flows.

Yes. Decisions act at once and the toast has Undo. See Reviewing a build.

A screenshot changes on every run. What can I do?

Section titled “A screenshot changes on every run. What can I do?”

A screenshot is called flaky when its image keeps returning to one it already had in the last 10 default-branch commits (3 flip-flops by default), or when two builds of the same commit produced different images. Flaky screenshots go to a triage queue instead of blocking review. You can also draw an ignore region over the part that moves, or raise the project's diff threshold (How screenshots are compared). See Triage and flaky screenshots.

Can I get notified in Slack, or file an issue from a build?

Section titled “Can I get notified in Slack, or file an issue from a build?”

Yes: Slack notices per project, Linear and Jira issues from a build, Figma frames next to a screenshot, and signed webhooks for your own receivers. See Integrations and Webhooks.

In your own Postgres (builds, reviews, settings) and your own storage (every screenshot, diff and thumbnail), which is local disk or any S3-compatible bucket. Back up both. See Database, Storage and Backups.

One container image and Postgres, plus storage. A small VM is enough to start. See Requirements and Docker Compose.

Mostly storage and its egress, then CPU for comparing images. Storage grows with changed screenshots rather than with builds, because files are stored once by their hash. Shorter retention and cheaper object storage are the biggest levers. See Performance and Retention and garbage collection.

A project keeps its builds for 30 days by default, and you can change it per project. Files nothing references any more are deleted after a grace period. The newest approved baseline on the default branch, for each build name, never expires. See Retention and garbage collection.

No, but without SMTP there are no sign-in codes, no invitations and no email notifications. Passwords and single sign-on still work. See Configuration.

The dashboard needs https on a real host, because sign-in cookies need it. Plain http is fine on localhost only. Hosted sites also need their own separate domain. See TLS and reverse proxy and Site domains.

Back up, start the new image and let it migrate. Run the same version of every process. See Upgrades and migrations.

Run circi admin doctor, then read Troubleshooting. For probes and logs, see Monitoring. For the messages the CLI and API return, see Errors and exit codes.

The dashboard has a phone layout and can be installed as an app. See Mobile and the installed app.