Skip to content

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.

Two variables are required. PUBLIC_URL has a default that only suits trying CirCI on one machine. Everything else is optional.

DATABASE_URLRequiredURL

The Postgres connection string. See Database.

BETTER_AUTH_SECRETRequired

Signs sessions and cookies. Generate it with openssl rand -base64 32.

PUBLIC_URLURLDefault http://localhost:3000

The https address people open, such as https://ci.acme.io. Set it for any install other people use.

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.
  • 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.

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.