Configure
Security
How CirCI protects secrets, tokens, files, other people's projects and hosted sites, and what leaves your server.
This page lists what the code does to keep an instance safe, so you can judge it and know what is left to you. It describes mechanisms, not guarantees: the code is the source, and where a protection depends on how you deploy, the page says so.
The instance secret
Section titled “The instance secret”BETTER_AUTH_SECRET (at least 32 characters) is the root of every key CirCI makes. Each use derives its own key under a separate label, so a value signed for one purpose is useless for another:
| Use | What it protects |
|---|---|
| Sealing credentials | Integration credentials (access tokens, bot tokens), the GitHub App's private key, webhook secret and client secret, instance settings that are secrets (such as the SMTP password and sign-in client secrets) and the web push private key. AES-256-GCM, stored as v1.<iv>.<tag>.<ciphertext> |
| Signed file links | Links to screenshots and diffs |
| OAuth state | The state of an integration's redirect, valid for 10 minutes |
| Hosted site cookies | The signature of a site's cookie |
| The setup code | First-run setup |
| Session cookies | Sessions (through better-auth) |
A sealed value that is malformed, tampered with or sealed under another secret reads as missing. Rotating the secret therefore signs everyone out, makes stored credentials unreadable (connections must be set up again) and invalidates web push subscriptions. Back it up with the database: see Backups.
Secrets in the dashboard are write-only: a saved password or client secret is never shown again.
Tokens
Section titled “Tokens”- Project CI tokens are
circi_followed by 43 characters of base64url (32 random bytes). A token belongs to one project and is shown once, when it is created or rotated. CirCI keeps only its SHA-256 hash and a short hint (circi_AbC1…). Rotating a token ends the old one at once. Requests to/v1and/v2without a valid token get 401 withWWW-Authenticate: Bearer. - Webhook signing secrets (
whsec_…) are shown once when a webhook is added or regenerated. Each delivery carriesCirCI-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 over<t>.<raw body>, so a captured request can't be replayed later. Receivers should reject old timestamps; the reference verifier allows 300 seconds. See Webhooks. - Git host webhooks into CirCI are verified against the exact bytes received (a signature or a token, by host) before the body is parsed. The secrets are derived from the instance secret.
Other people's projects
Section titled “Other people's projects”A person who isn't allowed to see something gets "not found", not "forbidden". A project someone isn't in, or a workspace they don't belong to, looks like one that doesn't exist, so its existence isn't revealed. "Forbidden" appears only to someone who can see the thing but lacks the role. Membership is always decided before the role. The full list of who may do what is in Members and roles.
A workspace can also refuse some sign-in methods, and a session made through a workspace's own single sign-on opens that workspace only. See Authentication.
Requests and cookies
Section titled “Requests and cookies”- Same origin. A dashboard request that changes something must carry the dashboard's own
Origin, or the server answers 403. A page on any other site, such as a hosted Storybook, can't make a signed-in browser do it. __Host-cookies. Overhttps, dashboard cookies take the__Host-prefix: Secure, no Domain, Path/, so a subdomain can't overwrite them.- Proxies. The client address is the socket's, unless
TRUSTED_PROXIESnames the proxies whoseX-Forwarded-Foris believed. A header a client sends to the sign-in endpoints is replaced. - Pages the server writes (the sites "not found", the "Web app not built" notice) load nothing: their Content-Security-Policy is
default-src 'none'with one inline stylesheet allowed by hash.
The code sets no other security headers on the dashboard itself. If your policy needs Strict-Transport-Security or a Content-Security-Policy for the dashboard, set them in the reverse proxy: see TLS and reverse proxy.
Screenshot files
Section titled “Screenshot files”Screenshots, diffs and thumbnails are stored by the SHA-256 of their content.
- Upload. A file is accepted only for a build that asked for that hash, and the storage driver writes it only if the bytes hash to what was announced; a mismatch is refused and nothing is stored.
- Reading.
GET /api/files/<hash>needs either a session whose user may see that file, or a signed link. A user without access gets "not found". - Signed links. A reply that includes a file carries a signed, expiring link for it. The signature covers the hash and the expiry, and the expiry is the end of a one-hour window, so a link lives between one and two hours and every link for a file in the same window is the same (so browsers keep their cached copy). A signed link needs no session.
- Serving. Files come with
X-Content-Type-Options: nosniffandContent-Security-Policy: sandbox; default-src 'none', so a file can't run as a page even if opened directly. - Workspace pictures are limited to 1 MB, accepted as PNG, JPEG or WebP, and re-encoded to PNG.
Requests CirCI makes on its own
Section titled “Requests CirCI makes on its own”Webhook receivers and a workspace's single sign-on issuer are addresses a person typed, and the server will call them. To keep that from reaching the server's own network:
- The address must be
httporhttpswith no username or password, and a public one: not an IP in a loopback, private, link-local (cloud metadata), shared, multicast or reserved range (IPv6 forms, including IPv4 inside IPv6, included), and notlocalhostor a name ending in.localhost,.local,.internal,.lanor.home.arpa, or a name without a dot. - A webhook's name is resolved again at delivery, because a name can point somewhere else later. A delivery to a private address is skipped and recorded.
- Redirects aren't followed, so a signed body can't be sent somewhere that wasn't configured. A delivery times out after 10 seconds.
- A workspace single sign-on issuer must be
https, and is checked when saved.
WEBHOOK_ALLOW_PRIVATE_ADDRESSES=true lifts the address rules for both, for receivers on your own network. It applies to every project and workspace on the instance.
Hosted sites
Section titled “Hosted sites”Uploaded sites run code you didn't write, so they are kept apart from the dashboard. The deployment side (the dedicated domain, the cookie rules you must check) is in Site domains; the mechanisms:
- Sites are served from the sites domain, never from the dashboard's origin, so their scripts can't read the dashboard's cookies or call its API as the visitor.
- Every request needs sign-in. A site's own cookie is
<session ID>.<signature>, valid for one site address only, host-only,HttpOnly,SameSite=Lax, one hour, and Secure with the__Host-prefix overhttps. It stands for a server-side row, which is what is revoked when a session ends. - Responses are
Cache-Control: private, no-cache, withX-Content-Type-Options: nosniff,Cross-Origin-Opener-Policy: same-origin,Cross-Origin-Resource-Policy: same-originandframe-ancestorslimited to the site itself and the dashboard. - Uploaded code can fill the cookie jar of the sites domain until requests are refused as too large. The server accepts the large headers and expires the cookies it doesn't recognize on the next request.
- Return addresses in the sign-in hand-off are same-site paths only: never
//host, a backslash or a scheme.
What leaves the instance
Section titled “What leaves the instance”CirCI makes outbound requests only to services you configure:
| To | When |
|---|---|
| Your storage (S3 or compatible) | Always, unless you use the local filesystem |
| SMTP server | Sign-in codes, invitations, notifications, new sign-in notices |
| Git hosts (GitHub, GitLab, Bitbucket) | Check runs, statuses, comments, importing repositories |
| Slack, Linear, Jira, Figma | When an integration is connected, for what it does |
| Webhook receivers | Build events, signed |
| Sign-in providers | When a person signs in with one |
| Browser push services | Notifications; the payload is encrypted for the browser (RFC 8291), so the push service only carries ciphertext |
The code has no analytics or error-reporting client and no update check. Profile pictures come from the account you sign in with, with a generated avatar when it has none, so no avatar service is contacted (see Account settings).