Skip to content

Getting started

Create a project

Make a project, find its settings and its CI token.

A project is one thing you test. Each project has its own CI token, baselines, review rules and settings.

Use New project on the projects page. Give it a Name (the address is derived from it), choose the Workspace, and set the Default branch (main unless yours differs). You can Link a repository at the same time; it's optional and needs a connected git host. If a GitHub App is connected, you can also import projects from your repositories, which links each one to its repository. You and the workspace's owners and admins can then open the project's Settings from its page.

CirCI
The projects page: projects grouped by workspace, each with its members, latest build and changes. New project is at the top right.
The projects page.
Terminal window
docker compose exec circi circi admin workspace create --name "Acme" --owner you@acme.io
docker compose exec circi circi admin project create --org acme --name "Web app"

project create prints the project's CI token. Options: --slug, --default-branch (default main), --member <email> (repeatable; adds a workspace member to the project) and --json.

A CI token identifies one project to the upload API. It starts with circi_, is shown once (store it in your CI's secret store), and is kept hashed. A token can only upload builds and read the status of its own project's builds. It can't read the dashboard.

To replace it, open the project's Settings › CI token, and rotate it. The old token stops working immediately. From the command line:

Terminal window
circi admin project rotate-token --org acme --project web-app
Setting Default What it does
Default branch main Builds on this branch become baselines.
Keep builds for 30 days Builds and sites older than this expire. Files nothing uses are deleted after a grace period.
Diff threshold 0% How much of a screenshot may differ before it counts as changed, as a share of its pixels. At 0%, any pixel change counts.
Approve default-branch builds automatically On Builds on the default branch are approved when they have a baseline.
Unreviewed changes block merging On Unreviewed changes keep the check red.

See Project settings for all of them.

Next: First upload.