Skip to content

Introduction

How a build flows

From CI upload to the merge gate, step by step.

A build is one upload of screenshots for one commit. It passes through four stages.

How a build flowsFour stages in order. Upload: CI sends screenshots with circi upload. Compare: the worker diffs each screenshot against the baseline. Review: people approve or reject changes in the dashboard. Merge gate: the check on the pull request, or the CI job when no repository is linked, passes once everything is approved.UploadCI sends screenshotscirci uploadCompareThe worker diffs each oneagainst the baselineReviewPeople approve or rejectin the dashboardMerge gateApproval decidespasses when approvedHow a build flowsFour stages in order. Upload: CI sends screenshots with circi upload. Compare: the worker diffs each screenshot against the baseline. Review: people approve or reject changes in the dashboard. Merge gate: the check on the pull request, or the CI job when no repository is linked, passes once everything is approved.UploadCI sends screenshotscirci uploadCompareThe worker diffs each oneagainst the baselineReviewPeople approve or rejectin the dashboardMerge gateApproval decidespasses when approved
  1. Upload. After your screenshot tests, CI runs this:

    npx circi upload ./screenshots --wait
    • The CLI collects every *.png under the folder (the screenshot's name is its path without .png) and hashes each file with SHA-256.
    • It reads the commit, branch, pull request and base branch from the CI environment (GitHub Actions, GitLab CI, Bitbucket Pipelines, Gitea and Forgejo Actions, CircleCI, Buildkite, Jenkins, Azure Pipelines).
    • It collects the git history it needs to find the right baseline. A shallow checkout is fine: it fetches the base branch and just enough history.
    • It creates the build, learns which files the server doesn't have yet, uploads only those, and tells CirCI the upload is complete. Unchanged screenshots are stored once, whatever the number of builds.
  2. Compare. When the last shard of the build arrives, the build moves to Processing and the worker (the background process that compares screenshots, started with the server by default) pairs screenshots by name with the baseline.

    • A screenshot only in this build is Added, only in the baseline Removed, with the same hash Unchanged (no work), and otherwise it's diffed.
    • A different image size is always a change, whatever the share of changed pixels. Otherwise a change is a change when it's bigger than the project's diff threshold. How screenshots are compared has the detail.
    • The worker writes a diff image and thumbnails, and sets the build's conclusion.
  3. Review. If anything changed, the build is Needs review. People open it in the dashboard (or from the GitHub check) and approve or reject each screenshot, or the whole build. Screenshots known to be Flaky are marked so reviewers can skip them. See Reviewing a build.

  4. Merge gate. What blocks the merge depends on whether the project is linked to a repository on a git host.

    • Linked (GitHub today with buttons and commands; GitLab and Bitbucket with statuses and comments): the CirCI check is the gate. Mark it as required in branch protection. circi upload --wait waits for processing and exits 0 even with unreviewed changes, so a green CI job isn't mistaken for a visual review. It fails only on processing errors and, in a project that blocks merges, on screenshots that couldn't be read. Approving in the dashboard or on GitHub updates the check within seconds, with no re-run.
    • Not linked: the CI job is the gate. --wait exits 1 while changes need review. After approval, re-run the job.
    • --gate status makes the git host's check the gate, and --gate exit-code makes the CI job the gate. Without --gate, the server chooses from the project's settings.

    Screenshots that couldn't be read. A file that isn't a valid PNG is marked Couldn't read and can't be approved. This follows the project's Unreviewed changes block merging setting, like a build that failed to process. With it on, the check fails and --wait exits 2. With it off, the check is neutral and --wait exits 0 with a warning that names each file. Upload the build again with valid PNGs to clear it.

The baseline for a build is the nearest earlier build of the same project and the same build name (--name, default default) that is approved, or that matched its own approved baseline.

  • For a pull request, CirCI walks the history from the merge base of the pull request and its 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. The build page says which source it used.
  • If there is none, every screenshot is new and waits for review.
  • A new build for the same project, build name and commit whose screenshots are identical to an already approved build is approved automatically, so "approve, then re-run the CI job" goes green. It never carries over a rejection or a changed screenshot.
  • Parallel jobs upload as shards of one build (--shard 2/4). CirCI processes the build when the last shard arrives. A shard that never arrives fails the build after UPLOAD_TIMEOUT_MINUTES (default 60), naming the missing shards.

Next: Key concepts.