Skip to content

Reference

Environment variables

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.

VariableDefaultMeaning
DATABASE_URLrequiredPostgres 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_SECRETrequiredSigns sessions and cookies. At least 32 characters (openssl rand -base64 32). Keep it secret and stable: changing it signs everyone out.
PUBLIC_URLhttp://localhost:3000The 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_PROXIESnoneReverse 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.
HOST0.0.0.0Address the HTTP server binds to.
PORT3000Port the HTTP server listens on (1 to 65535).
LOG_LEVELinfoOne of fatal, error, warn, info, debug, trace.
NODE_ENVproductiondevelopment, production or test. The image runs as production.
DATABASE_POOL_MAX10Largest number of Postgres connections one process keeps open.
CIRCI_MIGRATIONSsource tree layoutFolder of SQL migrations. The Docker image sets it to /app/migrations; set it when you run the bundle outside the image.
CIRCI_WEB_DISTsource tree layoutFolder with the built dashboard. The image sets it to /app/web; set it when you run the bundle outside the image.
VariableDefaultMeaning
STORAGE_DRIVERfsfs (local disk) or s3 (any S3-compatible service).
STORAGE_PATH/var/lib/circi/filesDirectory for the fs driver. In the compose file it is a Docker volume.
S3_BUCKETnoneBucket name. Required when STORAGE_DRIVER=s3.
S3_REGIONus-east-1Bucket region.
S3_ENDPOINTnoneA custom endpoint for R2, B2, MinIO or LocalStack. Leave empty for AWS. Must be a URL.
S3_FORCE_PATH_STYLEtrue when S3_ENDPOINT is set, otherwise falseUse path-style addressing (MinIO, LocalStack).
S3_ACCESS_KEY_IDnoneStatic credentials. Set both key variables, or neither to use the AWS credential chain (an IAM role).
S3_SECRET_ACCESS_KEYnoneSee S3_ACCESS_KEY_ID.
S3_CONNECT_TIMEOUT_SECONDS10Give up connecting after this long (1 to 600), so a dropped connection can't hang a request or job.
S3_REQUEST_TIMEOUT_SECONDS60Give up when S3 sends or accepts nothing for this long (1 to 3600). Idle time, not total time: large files keep flowing.

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.

VariableDefaultMeaning
WORKSPACE_CREATIONInstance settingsadminWho can create workspaces in the dashboard: admin (instance admins) or anyone (every signed-in account).
AUTH_PASSWORD_ENABLEDInstance settingstrueEmail and password sign-in. Setting it to false needs email codes to be available (SMTP), or nobody could sign in.
AUTH_EMAIL_ENABLEDInstance settingstrueSign-in codes by email. Only offered when SMTP is configured; false turns them off.
AUTH_SSO_ENABLEDInstance settingstrueSet false to hide single sign-on even with providers configured.
AUTH_GITHUB_CLIENT_IDInstance settingsnoneGitHub single sign-on app. Redirect URI to register: PUBLIC_URL/api/auth/callback/github.
AUTH_GITHUB_CLIENT_SECRETInstance settingsnoneSecret of the GitHub sign-in app.
AUTH_GOOGLE_CLIENT_IDInstance settingsnoneGoogle single sign-on. Redirect URI: PUBLIC_URL/api/auth/callback/google.
AUTH_GOOGLE_CLIENT_SECRETInstance settingsnoneSecret of the Google sign-in app.
AUTH_GITLAB_CLIENT_IDInstance settingsnoneGitLab single sign-on. Redirect URI: PUBLIC_URL/api/auth/callback/gitlab.
AUTH_GITLAB_CLIENT_SECRETInstance settingsnoneSecret of the GitLab sign-in app.
AUTH_GITLAB_URLInstance settingsgitlab.comAddress of a self-managed GitLab.
AUTH_OIDC_ISSUERInstance settingsnoneIssuer of any OpenID Connect provider (Okta, Entra ID, Keycloak, Authentik). Redirect URI: PUBLIC_URL/api/auth/callback/oidc.
AUTH_OIDC_CLIENT_IDInstance settingsnoneClient ID at the OIDC provider.
AUTH_OIDC_CLIENT_SECRETInstance settingsnoneClient secret at the OIDC provider.
AUTH_OIDC_NAMEInstance settingsnoneLabel of the sign-in button.
AUTH_OIDC_TRUSTED_FOR_EMAILInstance settingsfalseTrust 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.

VariableDefaultMeaning
SMTP_HOSTInstance settingsnoneOutgoing mail server. Without it, email sign-in codes, invitation mail and "new sign-in" mail are off.
SMTP_PORTInstance settings587 (465 when SMTP_SECURE is true)587 uses STARTTLS; 465 implicit TLS.
SMTP_SECUREInstance settingstrue when the port is 465Use implicit TLS.
SMTP_USERInstance settingsnoneUsername. Set SMTP_USER and SMTP_PASSWORD together, or neither for a server that needs no sign-in.
SMTP_PASSWORDInstance settingsnoneSee SMTP_USER.
SMTP_FROMInstance settingsnoneSender, 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.

VariableDefaultMeaning
GITHUB_APP_IDnoneGitHub App ID. Set GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY and GITHUB_APP_WEBHOOK_SECRET together or not at all.
GITHUB_APP_PRIVATE_KEYnoneThe app's PEM private key; \n escapes are fine.
GITHUB_APP_WEBHOOK_SECRETnoneSecret GitHub signs its webhooks with.
GITHUB_API_URLhttps://api.github.comFor GitHub Enterprise Server: https://ghe.example.com/api/v3.
GITHUB_API_TIMEOUT_SECONDS15How long one GitHub API request may take (0.1 to 600).
SLACK_CLIENT_IDInstance settingsnoneClient ID of the Slack app CirCI posts as.
SLACK_CLIENT_SECRETInstance settingsnoneClient secret of the Slack app.
SLACK_API_URLnoneOverride the Slack API address (tests, proxies).
VariableDefaultMeaning
STATIC_SITES_HOSTnoneA 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.
STATIC_SITES_MAX_MBInstance settings200Largest site upload in MB (1 to 5000).
VariableDefaultMeaning
CIRCI_DIFF_ENGINEnativenative 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_THREADScores - 1Threads of the js-workers engine (1 to 256). Caps its memory use.
UPLOAD_TIMEOUT_MINUTESInstance settings60Builds still uploading after this long fail, naming the shards that never arrived. 0 never.
GC_GRACE_HOURSInstance settings24Files nothing uses any more are deleted after this long. Builds and sites expire after the project's retention in days.
JOB_RETENTION_DAYSInstance settings14Finished background jobs (done or failed) are deleted after this many days. 0 keeps them.
JOB_RETRY_BASE_SECONDS2First wait before a failed job (webhook, git check, email) is retried; each further wait doubles. Mostly for tests.
JOB_RETRY_MAX_SECONDS300The longest wait between two attempts of a job.
VariableDefaultMeaning
WEBHOOK_ALLOW_PRIVATE_ADDRESSESfalseAllow 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 settings10How long a webhook receiver may take to answer a delivery (0.1 to 600).
VAPID_PUBLIC_KEYnoneWeb 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_KEYnoneSee VAPID_PUBLIC_KEY.
VAPID_SUBJECTPUBLIC_URLContact the push services may use. Must start with mailto: or https://.