Lists every environment variable CirCI reads, with its default and what it does.
Values are read once at start. Booleans accept true, false, 1, 0, yes and no. An empty value counts as unset. A bad value stops the process with a list of problems. Guidance is in Configuration.
The Docker Compose file only passes through the variables it lists: see Docker Compose.
Postgres connection string. The worker listens with Postgres LISTEN/NOTIFY, so use a direct connection or session pooling, not a transaction pooler such as PgBouncer in transaction mode.
BETTER_AUTH_SECRET
required
Signs sessions and cookies. At least 32 characters (openssl rand -base64 32). Keep it secret and stable: changing it signs everyone out.
PUBLIC_URL
http://localhost:3000
The dashboard address, any host you own (https://ci.acme.io). It must be the root of its own hostname (no sub-path). Use https outside local development; a plain http address on a public host logs a warning.
PREVIOUS_PUBLIC_URLS
(empty)
Comma-separated old dashboard addresses. Requests to them are redirected to PUBLIC_URL, so old links in pull request comments and emails keep working after a move. A previous address can't equal the current host.
TRUSTED_PROXIES
none
Reverse proxies whose X-Forwarded-For is believed: comma-separated IPs or CIDR ranges (10.0.0.5,172.16.0.0/12), or true for any hop (unsafe unless the app is reachable only through the proxy). Behind a proxy, set it to the proxy address, or every user shares the proxy address and one rate limit.
HOST
0.0.0.0
Address the HTTP server binds to.
PORT
3000
Port the HTTP server listens on (1 to 65535).
LOG_LEVEL
info
One of fatal, error, warn, info, debug, trace.
NODE_ENV
production
development, production or test. The image runs as production.
DATABASE_POOL_MAX
10
Largest number of Postgres connections one process keeps open.
CIRCI_MIGRATIONS
source tree layout
Folder of SQL migrations. The Docker image sets it to /app/migrations; set it when you run the bundle outside the image.
CIRCI_WEB_DIST
source tree layout
Folder with the built dashboard. The image sets it to /app/web; set it when you run the bundle outside the image.
Also editable in Instance settings. A variable that is set wins and locks the setting there; leave it unset to change it in the dashboard.
Variable
Default
Meaning
WORKSPACE_CREATIONInstance settings
admin
Who can create workspaces in the dashboard: admin (instance admins) or anyone (every signed-in account).
AUTH_PASSWORD_ENABLEDInstance settings
true
Email and password sign-in. Setting it to false needs email codes to be available (SMTP), or nobody could sign in.
AUTH_EMAIL_ENABLEDInstance settings
true
Sign-in codes by email. Only offered when SMTP is configured; false turns them off.
AUTH_SSO_ENABLEDInstance settings
true
Set false to hide single sign-on even with providers configured.
AUTH_GITHUB_CLIENT_IDInstance settings
none
GitHub single sign-on app. Redirect URI to register: PUBLIC_URL/api/auth/callback/github.
AUTH_GITHUB_CLIENT_SECRETInstance settings
none
Secret of the GitHub sign-in app.
AUTH_GOOGLE_CLIENT_IDInstance settings
none
Google single sign-on. Redirect URI: PUBLIC_URL/api/auth/callback/google.
AUTH_GOOGLE_CLIENT_SECRETInstance settings
none
Secret of the Google sign-in app.
AUTH_GITLAB_CLIENT_IDInstance settings
none
GitLab single sign-on. Redirect URI: PUBLIC_URL/api/auth/callback/gitlab.
AUTH_GITLAB_CLIENT_SECRETInstance settings
none
Secret of the GitLab sign-in app.
AUTH_GITLAB_URLInstance settings
gitlab.com
Address of a self-managed GitLab.
AUTH_OIDC_ISSUERInstance settings
none
Issuer of any OpenID Connect provider (Okta, Entra ID, Keycloak, Authentik). Redirect URI: PUBLIC_URL/api/auth/callback/oidc.
AUTH_OIDC_CLIENT_IDInstance settings
none
Client ID at the OIDC provider.
AUTH_OIDC_CLIENT_SECRETInstance settings
none
Client secret at the OIDC provider.
AUTH_OIDC_NAMEInstance settings
none
Label of the sign-in button.
AUTH_OIDC_TRUSTED_FOR_EMAILInstance settings
false
Trust the provider's email addresses (an existing account with the same email is then linked). Set true only if the provider verifies every address it reports. GitHub and Google are always trusted.
Also editable in Instance settings (the Mail server section). Set SMTP_HOST and it wins and locks the section. Check it with circi admin mail test --to you@acme.io.
Variable
Default
Meaning
SMTP_HOSTInstance settings
none
Outgoing mail server. Without it, email sign-in codes, invitation mail and "new sign-in" mail are off.
SMTP_PORTInstance settings
587 (465 when SMTP_SECURE is true)
587 uses STARTTLS; 465 implicit TLS.
SMTP_SECUREInstance settings
true when the port is 465
Use implicit TLS.
SMTP_USERInstance settings
none
Username. Set SMTP_USER and SMTP_PASSWORD together, or neither for a server that needs no sign-in.
SMTP_PASSWORDInstance settings
none
See SMTP_USER.
SMTP_FROMInstance settings
none
Sender, e.g. CirCI . Required when SMTP_HOST is set.
The Slack app is also editable in Instance settings (set SLACK_CLIENT_ID and it wins and locks it). The GitHub App can also be created from Instance settings (manifest flow), see the GitHub page.
Variable
Default
Meaning
GITHUB_APP_ID
none
GitHub App ID. Set GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY and GITHUB_APP_WEBHOOK_SECRET together or not at all.
GITHUB_APP_PRIVATE_KEY
none
The app's PEM private key; \n escapes are fine.
GITHUB_APP_WEBHOOK_SECRET
none
Secret GitHub signs its webhooks with.
GITHUB_API_URL
https://api.github.com
For GitHub Enterprise Server: https://ghe.example.com/api/v3.
GITHUB_API_TIMEOUT_SECONDS
15
How long one GitHub API request may take (0.1 to 600).
A separate, dedicated domain for hosted sites (Storybook, reports). Hosting is off until it is set. Read the cookie rules on the Site domains page first. CirCI refuses a value that equals, contains or shares a parent domain with the dashboard host.
native runs the pixel comparison in the Rust addon the image ships (about twice the builds per minute under load). If it can't load, the worker logs a warning and uses js. js runs on the worker's event loop. js-workers runs the same JavaScript comparison in a pool of worker threads (no native module, about 2.6 times the memory).
CIRCI_DIFF_THREADS
cores - 1
Threads of the js-workers engine (1 to 256). Caps its memory use.
UPLOAD_TIMEOUT_MINUTESInstance settings
60
Builds still uploading after this long fail, naming the shards that never arrived. 0 never.
GC_GRACE_HOURSInstance settings
24
Files nothing uses any more are deleted after this long. Builds and sites expire after the project's retention in days.
JOB_RETENTION_DAYSInstance settings
14
Finished background jobs (done or failed) are deleted after this many days. 0 keeps them.
JOB_RETRY_BASE_SECONDS
2
First wait before a failed job (webhook, git check, email) is retried; each further wait doubles. Mostly for tests.
Allow webhooks to private and loopback addresses. By default they are refused (and an OIDC issuer must be a public https address). Set true if your receivers live on your own network.
WEBHOOK_TIMEOUT_SECONDSInstance settings
10
How long a webhook receiver may take to answer a delivery (0.1 to 600).
VAPID_PUBLIC_KEY
none
Web push signing key pair. Leave unset and the server makes its own on first use and keeps them in the database. Pin them when several instances share keys, or after a restore. Set both or neither.
VAPID_PRIVATE_KEY
none
See VAPID_PUBLIC_KEY.
VAPID_SUBJECT
PUBLIC_URL
Contact the push services may use. Must start with mailto: or https://.