Skip to content

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.io

Whether the CirCI check or the CI job blocks the merge, and when --wait exits 2, is explained in How a build flows.

CircleCI, Buildkite and Azure Pipelines are detected as well; their environment is read the same way.

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).

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 --wait

Every 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.

--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 mobile

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.

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.