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.
Which value applies
Section titled “Which value applies”Every setting has up to three sources, and the first one that exists wins.
- 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."
- The value saved in the dashboard.
- The default.
To hand a setting over to the dashboard, remove its variable and restart once. To lock it again, set the variable.
What you can change
Section titled “What you can change”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.
Who can create workspaces
Section titled “Who can create workspaces”Let every signed-in account create workspacesOff, only instance admins create workspaces, and everyone else joins through an invitation or a verified email domain. On, every signed-in account can.
Sign-in methods
Section titled “Sign-in methods”Password, Email code, Single sign-onThe 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.
Single sign-on providers
Section titled “Single sign-on providers”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.
Mail server
Section titled “Mail server”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.
Slack app
Section titled “Slack app”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.
GitHub App
Section titled “GitHub App”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.
GitHub App
Section titled “GitHub App”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.
Storage and limits
Section titled “Storage and limits”| 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 |
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.
Read-only on this page
Section titled “Read-only on this page”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.
The other Instance pages
Section titled “The other Instance pages”| 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. |
See Instance administration for how admins use these pages.