Introduction
FAQ
Short answers to the questions people ask first, each with the page that has the details.
Getting screenshots in
Section titled “Getting screenshots in”What takes the screenshots?
Section titled “What takes the screenshots?”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.
Which image formats work?
Section titled “Which image formats work?”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.
Which CI systems are supported?
Section titled “Which CI systems are supported?”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.
Does CirCI choose the browsers?
Section titled “Does CirCI choose the browsers?”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.
Can I switch from Argos?
Section titled “Can I switch from Argos?”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.
Baselines and reviews
Section titled “Baselines and reviews”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.
How does CirCI choose the baseline?
Section titled “How does CirCI choose the baseline?”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.
Who can approve changes?
Section titled “Who can approve changes?”Any workspace member who can see the project. Changing settings, rules, tokens and integrations needs an owner or an admin. See Members and roles.
Will an unreviewed change block my merge?
Section titled “Will an unreviewed change block my merge?”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.
Can I take back an approval?
Section titled “Can I take back an approval?”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.
Running it
Section titled “Running it”Where does my data live?
Section titled “Where does my data live?”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.
What does it need to run?
Section titled “What does it need to run?”One container image and Postgres, plus storage. A small VM is enough to start. See Requirements and Docker Compose.
How much does it cost to run?
Section titled “How much does it cost to run?”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.
How long are builds kept?
Section titled “How long are builds kept?”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.
Do I need an email server?
Section titled “Do I need an email server?”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.
Does it need a domain and https?
Section titled “Does it need a domain and https?”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.
How do I upgrade?
Section titled “How do I upgrade?”Back up, start the new image and let it migrate. Run the same version of every process. See Upgrades and migrations.
Something is wrong. Where do I look?
Section titled “Something is wrong. Where do I look?”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.
Can I use it on my phone?
Section titled “Can I use it on my phone?”The dashboard has a phone layout and can be installed as an app. See Mobile and the installed app.