Settings
Project settings
Every project setting, what it changes, who can change it, and which ones save on their own.
A project's settings decide how its builds are compared, what holds back a merge, who reviews, and what gets connected to it.
Where to open them
Section titled “Where to open them”- The project page's Settings button, and the Project settings item when you right-click a project in the sidebar. Both are shown only to owners and admins.
- CommandK, then type the page's name (for example "Webhooks"). Inside settings the menu offers that area's pages and the way back, and nothing of the app.
- Settings in the workspace menu, then Projects, then the project. See Workspace settings.
The hub lists the project's pages in three groups, each with a one-line summary such as "2 webhooks" or "3 rules". Inside a page, the sidebar lists the same pages under the project's name (General, Members, CI token and the rest), next to the account, instance and workspace entries. The sidebar's Back to … at the top, named for the page of the app you came from, is the only way out of settings. The section of the page you're on is listed first and open, and the other sections (Account, Workspace, Projects, and Instance for instance admins) are folded until you open them. On a phone the sections open from a sheet, and the header's close button is the way out:
| Group | Pages |
|---|---|
| Project | General, Members, CI token |
| Reviews | Reviews and triage, Ignore regions |
| Connections | Webhooks, Sites |
Who can do what
Section titled “Who can do what”Owners and admins of the workspace change a project's settings. A project member who isn't an owner or admin sees only Members and Ignore regions, read-only, and is sent back to the hub from the other pages. Someone who can't see the project at all gets "not found". See Members and roles.
Creating a project
Section titled “Creating a project”Owners and admins create projects from the Projects page with New project. Step 1 asks for the workspace, a Name, a Default branch (builds on it become the baselines other branches compare with) and, optionally, a repository to link. Step 2 shows the project's CI token once, with a CI example to copy. Copy it now: later you can only rotate it. See Create a project. Several repositories can also be imported at once from a connected git host; see GitHub.
General
Section titled “General”The page is split into sections. What only changes how the project looks saves by itself, and every section that changes how builds are judged or linked has its own Save changes and Discard:
At the top, with no Save button:
- Display name, with the icon and color tile beside it. The name saves when you leave the field, with a toast ("Renamed the project to …") that carries Undo. Picking a color or an icon saves at once ("Icon and color saved").
Then the sections, Details, Repository, Comparison, Merge gate and Hosted sites. Each section with fields (all but Repository, whose buttons act at once) has its own Save changes and Discard. They appear when something in that section changes, and stay at the bottom of the panel while any of the section is in view, so they're never far from the field you're editing. Saving one section leaves what you typed in another alone. When several sections have changes, only the one you edited last has the primary button.
Details
Section titled “Details”- URL slug, used in addresses and in
circi admincommands. Changing it breaks existing links, including bookmarks and the links in existing pull request comments; new builds post the new address. The CI token keeps working. - Default branch: its approved builds are the baselines. It must be a valid git branch name.
Repository
Section titled “Repository”Shows the linked repository, or "No repository linked". Link a repository (or Change) goes to the workspace's integrations, because git hosts are connected there. Remove (owners and admins) stops CirCI posting checks and comments on that repository's pull requests; builds already uploaded stay. With a repository linked, CirCI posts a check named CirCI / <build name> and one summary comment on each pull request. See GitHub, GitLab and Bitbucket. If the connection needs attention, a banner at the top says so.
Comparison
Section titled “Comparison”| Setting | Meaning | Limits |
|---|---|---|
| Diff threshold | How much of a screenshot may differ before it counts as changed, as a share of its pixels. A change of size always counts. Default 0% | 0% to 100% |
| Keep builds for | Older builds and their hosted sites expire. The newest approved baseline on the default branch never does | 1 to 3650 days. New projects start at 30 |
See How screenshots are compared for what the threshold does, and Retention and garbage collection.
Merge gate
Section titled “Merge gate”What the check on a pull request says while changes wait for review. It only blocks merging if the repository marks the check as required.
- Unreviewed changes block merging: the check stays pending until someone approves. Off: it passes with a "changes to review" summary.
- Flaky-only changes block merging: when the only changes are to flaky screenshots. Choose Inherit from workspace, On or Off. See Triage and flaky screenshots.
- Approve default-branch builds automatically: builds on the default branch become the new baseline without review. Needs an approved baseline, so a project's first build is always reviewed.
Hosted sites
Section titled “Hosted sites”Host static sites is shown only when the instance has a sites domain. See Hosted sites.
Danger zone
Section titled “Danger zone”Delete project removes the project with its builds, screenshots, hosted sites, rules and webhooks, and stops its CI token working. Screenshot files are cleaned up by retention afterwards. You type the confirmation phrase, workspace/project, to enable the button. It can't be undone.
Members
Section titled “Members”Who is in the project and their role. Owners and admins see every project; a member sees the projects they belong to. A member who isn't an owner or admin sees the list and can Leave project. Owners and admins can Add members (picking from the workspace's members) and Remove from project. Removing yourself reads Leave project.
CI token
Section titled “CI token”The page shows the token as a hint (never the full secret), when it was created and by whom, and when it was last used. Rotate token makes a new token and deletes the old one: the old one stops working at once, so CI fails until you update its secret. The new token is shown once. The page also shows the two secrets CI needs, CIRCI_TOKEN and CIRCI_API_URL, with the upload command and its exit codes; when a repository is linked it explains that the check on the pull request is the gate. See CLI.
Reviews and triage
Section titled “Reviews and triage”The Reviews group's page: review rules, the review target, automation, the triage rotation, the flaky threshold and the snooze default. Rules apply as soon as you confirm them; the rest saves with Save changes. See Review requests and rules and Triage and flaky screenshots.
Ignore regions
Section titled “Ignore regions”A list of the screenshots that have ignore regions, each opening its baseline inside settings. See Baselines and ignore regions.
Webhooks
Section titled “Webhooks”Add webhook takes an Address and the Events to send: build.completed (a build finished processing, with its conclusion) and build.reviewed (someone approved or rejected a build). The address must be public: localhost, private networks and cloud metadata addresses are refused. The signing secret is shown once.
Each webhook offers Send test, Regenerate secret (the old secret stops signing at once) and Remove, and lists its recent deliveries. Deliveries are signed JSON; any answer other than 2xx is retried 8 times with backoff, and redirects aren't followed. See Webhooks for the payloads and how to check a signature.
Each hosted site's branch addresses, uploads and custom domain, in the same page the sidebar's Sites opens. See Hosted sites.