Skip to content

Configure

Instance settings

What an instance admin changes in the dashboard, which environment variable locks each setting, and how the two work together.

Instance admins open Instance in the sidebar, then Instance settings. The page holds the settings of the whole installation, and most of them can be changed there, with no restart.

CirCI
The Instance settings page. The dashboard address and its old addresses are read-only and name their variables. Password, Email code and Single sign-on are checked under Sign-in methods. Single sign-on providers says there are none yet, and Who can create workspaces is unchecked.
Instance settings in a development instance. The settings that wait for Save changes are on the same page as the ones that name a variable.

Every setting has up to three sources, and the first one that exists wins.

  1. The environment variable, when it's set. The setting is locked: the page shows Set by VARIABLE, its control is disabled, and a save through the API is refused with "Set by VARIABLE in the environment: change it there."
  2. The value saved in the dashboard.
  3. The default.

To hand a setting over to the dashboard, remove its variable and restart once. To lock it again, set the variable.

Each section of the page saves with Save changes, and Discard reverts it. The two exceptions are the single sign-on providers, which apply from their own dialog, and the GitHub App, which has its own button.

Let every signed-in account create workspacesDefault off (instance admins only)

Off, only instance admins create workspaces, and everyone else joins through an invitation or a verified email domain. On, every signed-in account can.

Password, Email code, Single sign-onDefault all on

The outer limit. Each workspace can turn methods off for its own people, never on beyond this. Email codes need a mail server, and single sign-on needs at least one provider.

Saving refuses a change that would leave nobody able to sign in, for example turning the password off while email codes have no mail server. The message says which method to keep.

GitHub, Google, GitLab and OpenID Connect providers for every workspace. Add provider opens a dialog with the provider, the Name on the sign-in button, the Client ID, the Client secret, an Issuer for OpenID Connect or a GitLab address for a self-managed GitLab, and whether the provider only reports addresses its people own. The dialog shows the redirect address to register at the provider.

A provider set by the AUTH_* variables is listed as Set by AUTH_GITHUB_* (or the provider's own name), and can't be edited or removed here.

The SMTP Host, Port, Use TLS from the start, User name, Password and From address, and Send a test mail to your own address. Remove the mail server turns mail off again. With SMTP_HOST set the section is locked and shows the server and sender. Without mail, nobody gets sign-in codes, invitations or new sign-in notices.

The Client ID and Client secret of the Slack app CirCI posts as, and Remove the Slack app. With SLACK_CLIENT_ID set, the section is locked. See Slack.

A section at the bottom of the page, with a badge: Not set up, Environment (the GITHUB_APP_* variables, which can't be edited here) or Created here. Create GitHub App sends you to GitHub with the App's name, address, permissions and events filled in; you confirm it there and install it. CirCI stores what GitHub returns, encrypted. See GitHub.

A section at the bottom of the page, with a badge: Not set up, Environment (the GITHUB_APP_* variables, which can't be edited here) or Created here. Create GitHub App sends you to GitHub with the App's name, address, permissions and events filled in; you confirm it there and install it. CirCI stores what GitHub returns, encrypted. See GitHub.

Setting on the page Variable Default Range
New projects keep builds for none (a dashboard setting only) 30 days 1 to 3650
Unused files are deleted after GC_GRACE_HOURS 24 hours 0 to 8760
A build still uploading fails after UPLOAD_TIMEOUT_MINUTES 60 minutes (0 never) 0 to 10080
Finished background jobs are kept for JOB_RETENTION_DAYS 14 days (0 keeps them) 0 to 3650
A webhook receiver may take up to WEBHOOK_TIMEOUT_SECONDS 10 seconds 1 to 600
Largest hosted site STATIC_SITES_MAX_MB 200 MB 1 to 5000
CirCI
The Storage and limits section: Local disk with its variable, then number fields for new project retention, unused files, upload timeout, job retention and webhook timeout, and the Hosted sites section saying Not set up.
Storage and limits and Hosted sites. A limit set by its variable shows the variable and a disabled field.

New projects keep builds for is the retention a new project starts with. It's a real setting with no environment variable: each project then changes its own in its settings, and the instance value doesn't touch existing projects. See Retention and garbage collection.

These name their variable and are changed there, with a restart.

Setting Variable
Dashboard address, and the old addresses that redirect to it PUBLIC_URL, PREVIOUS_PUBLIC_URLS
Storage driver STORAGE_DRIVER and the S3_* settings
Whether webhooks may call private addresses WEBHOOK_ALLOW_PRIVATE_ADDRESSES
Hosted sites domain, or "Not set up" STATIC_SITES_HOST

Deployment values that don't appear on the page at all: DATABASE_URL, BETTER_AUTH_SECRET, HOST, PORT, TRUSTED_PROXIES and CIRCI_DIFF_ENGINE. The environment variable reference marks every variable that is also editable in the dashboard.

Page What it does
Accounts Every account. Change an email, ban or unban.
Workspaces Every workspace on the instance, deleted ones too, and creating one. Instance admins see a workspace's projects only if they belong to it.
Health The same checks as circi admin doctor, the background jobs per queue, the domains and cookies check, and the Setup code.
CirCI
The Health page, scrolled to Domains and cookies, then Background jobs with waiting, running, oldest waiting, failed and retrying counts, the Queues list and the Setup code state.
Health. Run checks again repeats what circi admin doctor reports.

See Instance administration for how admins use these pages.