In a GitLab Linux package installation, why does editing /etc/gitlab/gitlab.rb change nothing, and which settings belong there rather than in the Admin area?
answer
- a declaration, not live config
- one command applies it
- generated files get overwritten
- per node versus whole instance
basics
~20 sIn the Linux package, gitlab.rb is a declaration: nothing changes until sudo gitlab-ctl reconfigure renders it into each service's configuration. Node wiring such as external_url lives there; instance-wide policy lives in the Admin area, stored in the database.
solid answer
~40 s`/etc/gitlab/gitlab.rb` is Ruby that `gitlab-ctl reconfigure` executes as root to render the configuration of every bundled service; until you run it, the edit is only text on disk, and some settings also need `gitlab-ctl restart`. Files it generates, such as `/var/opt/gitlab/gitlab-rails/etc/gitlab.yml`, are overwritten on the next reconfigure, so hand edits there vanish. `gitlab.rb` holds what one node needs to start and find its peers: `external_url`, which components run on it, the PostgreSQL, Redis and Gitaly addresses, TLS and SMTP. The **Admin** area holds instance-wide application settings, such as **Allow new user accounts** or visibility defaults, stored in the database, so one change reaches every node once the application settings cache expires (60 seconds by default). On a multi-node install every node has its own `gitlab.rb`, and they share one `gitlab-secrets.json`.
code
ini · 8 lines# /etc/gitlab/gitlab.rb on one Rails node of a multi-node install
external_url 'https://gitlab.example.com'
postgresql['enable'] = false
redis['enable'] = false
gitaly['enable'] = false
gitlab_rails['db_host'] = 'db.example.com'
gitlab_rails['redis_host'] = 'redis.example.com'
gitlab_rails['application_settings_cache_seconds'] = 60go deeper
Remember the pair: edit /etc/gitlab/gitlab.rb, then run sudo gitlab-ctl reconfigure. Instance policy is changed in the Admin area instead.
Explain what reconfigure renders, why generated files must not be edited, and why Admin area settings reach every node after a cache interval.
Keep a multi-node install consistent: per-node gitlab.rb under change control, one shared secrets file, both backed up outside gitlab-backup, and no stray EXTERNAL_URL.
Decide how configuration is owned at scale: configuration management for gitlab.rb, review for Admin area policy changes, and who may write files that run as root.
## Two places configuration lives A GitLab Self-Managed instance installed with the **Linux package** is configured in two different places, and confusing them is the commonest early mistake. - **`/etc/gitlab/gitlab.rb`** is a file on each server. It describes that node: its address, which bundled components it runs, and how it reaches the others. - The **Admin** area is a web interface for instance administrators. Its settings are **application settings** stored in the GitLab database, shared by every node. It exists on GitLab Self-Managed and GitLab Dedicated; on GitLab.com customers have no **Admin** area. ## What `gitlab-ctl reconfigure` does Editing `gitlab.rb` changes nothing by itself. The file only takes effect when you run: ```bash sudo gitlab-ctl reconfigure ``` That command: 1. Executes `gitlab.rb` as Ruby, as the `root` user, including any file pulled in with `from_file`. 2. Renders each bundled service's own configuration, for example the Rails `gitlab.yml` under `/var/opt/gitlab/gitlab-rails/etc/`. 3. Brings the services on that node into line with the result. Some settings also need `sudo gitlab-ctl restart` before they are picked up; the documentation for such a setting says "reconfigure and restart", as it does for the application settings cache interval. Because the rendered files are regenerated every time, **never edit them by hand**: the next reconfigure, including the one a package upgrade triggers automatically, overwrites them. ## Which setting goes where | Lives in `gitlab.rb` (per node) | Lives in the **Admin** area (whole instance) | |---|---| | `external_url`, the address users and clone URLs use | **Allow new user accounts**, **Require admin approval for new user accounts** | | Which components run here (`postgresql['enable']`, `gitaly['enable']`) | Default visibility and access controls | | Addresses of PostgreSQL, Redis and Gitaly (`gitlab_rails['db_host']`, `gitlab_rails['redis_host']`) | Account and limit settings, rate limits | | TLS certificates, SMTP, storage paths | The subscription and its activation code | | `gitlab_rails['application_settings_cache_seconds']` | Instance-wide CI/CD defaults | A rough rule: if a setting is needed **before the application can start** or differs **between nodes**, it is in `gitlab.rb`; if it is **policy for users and projects**, it is in the **Admin** area. ## Timing of Admin area changes GitLab caches application settings, by default for **60 seconds**, so an **Admin** area change can take up to that long to show on every node. The interval is itself a `gitlab.rb` setting, `gitlab_rails['application_settings_cache_seconds']`. GitLab recommends keeping it above `0`, because `0` loads the `application_settings` table on every request and adds load to Redis and PostgreSQL. ## Traps worth knowing - **`EXTERNAL_URL` in the environment.** It is read during package installs and upgrades and written into `gitlab.rb` as `external_url`. Left set globally, a later package upgrade silently replaces the value in the file; pass it only on the install command. - **Write access to `gitlab.rb` is root access**, because reconfigure runs the file as Ruby under `root`. - **Multi-node drift.** Each node has its own `gitlab.rb`; the reference architectures also copy one `/etc/gitlab/gitlab-secrets.json` from the first node to every other node, because the secrets must match. - **Backups.** `gitlab-backup create` does not include `/etc/gitlab`. Back up `gitlab.rb` and `gitlab-secrets.json` separately; without the secrets file, encrypted values in the database cannot be decrypted after a restore. ## The same split on other offerings - **Helm chart installs:** the chart's values play the role of `gitlab.rb` and are applied by upgrading the release; the **Admin** area behaves the same. - **GitLab Dedicated:** there is no server access and no `gitlab.rb`. Instance-level infrastructure settings such as SAML single sign-on or an IP allowlist are made through the Switchboard portal, while the **Admin** area is available as usual. - **GitLab.com:** neither layer is yours. Customers configure top-level groups and projects; instance settings are GitLab's, published on its GitLab.com settings page.
- An administrator fixed a setting by editing the generated gitlab.yml on a Linux package node, and the fix disappeared after the next package upgrade. Why?The generated `/var/opt/gitlab/gitlab-rails/etc/gitlab.yml` is rewritten on every `gitlab-ctl reconfigure`, and a package upgrade runs reconfigure automatically unless `/etc/gitlab/skip-auto-reconfigure` exists. The change belongs in `gitlab.rb`, translated to its key, for example `gitlab_rails['gitlab_default_theme']`.
- Why must gitlab-secrets.json match on every node of a multi-node Linux package install, and why back it up separately?It holds the keys GitLab uses to encrypt values in the shared database, so every node must use the same file; the reference architectures copy it from the first node. `gitlab-backup create` leaves `/etc/gitlab` out, and a restore without that file cannot decrypt encrypted database values.
- Saving gitlab.rb applies the change immediately
- Edit the generated gitlab.yml when gitlab.rb lacks a key
- Sign-up restrictions belong in gitlab.rb on each node
- gitlab-backup create also saves /etc/gitlab and the secrets file
- Setting the application settings cache to 0 is the safe default