Upload from CI
CI examples
Copy-paste setups for uploading screenshots from GitHub Actions, GitLab CI, Bitbucket Pipelines, Gitea and Jenkins, including sharded runs.
Every example uploads a directory of PNG screenshots with circi upload. Put the project's token in your CI's secret store as CIRCI_TOKEN, and your CirCI address in CIRCI_API_URL. The CLI reads the commit, branch and pull request from the CI's environment. It also needs enough git history to find the baseline. Shallow checkouts work, because it fetches the base branch and a little more, but a full fetch is faster for large repositories.
- uses: actions/checkout@v4 with: { fetch-depth: 0 }- run: npx playwright test # writes screenshots to ./screenshots- run: npx @circi/cli upload ./screenshots --wait env: CIRCI_TOKEN: ${{ secrets.CIRCI_TOKEN }} CIRCI_API_URL: https://ci.acme.ioWhether the CirCI check or the CI job blocks the merge, and when --wait exits 2, is explained in How a build flows.
visual: script: - npx playwright test - npx @circi/cli upload ./screenshots --wait variables: GIT_DEPTH: 0Set CIRCI_TOKEN and CIRCI_API_URL under Settings, CI/CD, Variables. For a sharded job use parallel: 4 and --shard $CI_NODE_INDEX/$CI_NODE_TOTAL.
- step: script: - npx playwright test - npx @circi/cli upload ./screenshots --waitAdd the variables under Repository settings, Pipelines, Variables.
The GitHub Actions example works as is: the environment looks the same.
sh 'npx playwright test'withCredentials([string(credentialsId: 'circi-token', variable: 'CIRCI_TOKEN')]) { sh 'CIRCI_API_URL=https://ci.acme.io npx @circi/cli upload ./screenshots --wait'}Jenkins doesn't say which pull request a build is for unless you pass it: set CIRCI_PR_NUMBER, CIRCI_BRANCH and CIRCI_BASE_BRANCH (the multibranch plugin provides CHANGE_ID, BRANCH_NAME and CHANGE_TARGET).
CircleCI, Buildkite and Azure Pipelines are detected as well; their environment is read the same way.
First build and the gate
Section titled “First build and the gate”A project's first build has no baseline, so every screenshot is Added and needs review before the gate opens, even on the default branch. Auto-approve applies only once there is an approved baseline, so someone approves every screenshot once. Pull requests that change only flaky screenshots can pass without review when the workspace or project says flaky changes don't block (see Triage and flaky screenshots).
Sharded runs
Section titled “Sharded runs”strategy: matrix: { shard: [1, 2, 3, 4] }steps: - run: npx playwright test --shard=${{ matrix.shard }}/4 - run: npx @circi/cli upload ./screenshots --shard ${{ matrix.shard }}/4 --waitEvery job uploads its own screenshots; CirCI joins them into one build and processes it when the fourth arrives. A shard that never arrives fails the build after UPLOAD_TIMEOUT_MINUTES (default 60), naming the missing shards. A re-run of the workflow is a new attempt and starts a new build.
Several builds per commit
Section titled “Several builds per commit”--name chromium and --name mobile give each kind of build its own baselines:
- run: npx @circi/cli upload ./screenshots-chromium --name chromium- run: npx @circi/cli upload ./screenshots-mobile --name mobileOverride what's detected
Section titled “Override what's detected”CIRCI_COMMIT, CIRCI_BRANCH, CIRCI_PR_NUMBER and CIRCI_BASE_BRANCH replace what is detected. CIRCI_PARALLEL_NONCE ties shards together when the CI isn't recognized.
Exit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
0 |
Uploaded. With --wait: the build passed, or the git host's check is the gate. |
1 |
Visual changes need review and this job is the gate. |
2 |
An error. |
See the CLI reference.