Configure
Configuration
How CirCI is configured, and where each kind of setting lives.
CirCI is configured through environment variables, read once at start by @circi/config. A bad configuration stops the process with one line per problem (Invalid configuration: - BETTER_AUTH_SECRET: is required …) before anything starts.
The full list, with defaults, is the environment variable reference.
The minimum
Section titled “The minimum”Two variables are required. PUBLIC_URL has a default that only suits trying CirCI on one machine. Everything else is optional.
DATABASE_URLThe Postgres connection string. See Database.
BETTER_AUTH_SECRETSigns sessions and cookies. Generate it with openssl rand -base64 32.
PUBLIC_URLThe https address people open, such as https://ci.acme.io. Set it for any install other people use.
Rules between variables
Section titled “Rules between variables”Some variables only make sense together. The server checks them at start and prints one line per problem.
| Variables | Rule |
|---|---|
STORAGE_DRIVER=s3 |
Needs S3_BUCKET. S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY are both set or both left out. |
SMTP_HOST |
Needs SMTP_FROM. SMTP_USER goes with SMTP_PASSWORD. |
GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_WEBHOOK_SECRET |
All three or none. |
VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY |
Both, and a matching P-256 pair. |
PUBLIC_URL, PREVIOUS_PUBLIC_URLS |
PUBLIC_URL is the root of its own hostname. The previous list can't contain the current host. |
STATIC_SITES_HOST |
Refused if it's the dashboard host, its parent or child, or shares its parent domain. |
AUTH_EMAIL_ENABLED=true |
Without SMTP this only logs a warning, and email sign-in stays off. |
AUTH_PASSWORD_ENABLED=false |
Needs email codes to be available, or nobody could sign in. |
Where a setting lives
Section titled “Where a setting lives”- Environment variables are for the deployment: addresses, secrets, storage, timeouts, the diff engine.
- Instance settings in the dashboard hold the settings an instance admin should change without a restart: who can create workspaces, sign-in methods, limits, mail, Slack and single sign-on providers. A variable that is set wins and locks its setting; otherwise the saved value applies, then the default. See Instance settings.
- Workspace settings and project settings hold what workspace owners and admins decide: Workspace settings, Project settings.
Secrets
Section titled “Secrets”BETTER_AUTH_SECRET signs sessions and cookies: keep it stable (changing it signs everyone out) and back it up. Don't commit .env. Secrets can be passed as ordinary environment variables or with your orchestrator's secret mechanism; the variables take the value itself, not a file path.