Text of docs.gitlab.com › omnibus › settings › configuration as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Configuration options for Linux package installations | GitLab Docs

/ Configuration options for Linux package installations Tier : Free, Premium, Ultimate Offering : GitLab Self-Managed To configure GitLab, set the relevant options in the /etc/gitlab/gitlab.rb file. gitlab.rb.template contains a complete list of available options. New installations have all the options of the template listed in /etc/gitlab/gitlab.rb by default. The examples provided when you edit /etc/gitlab/gitlab.rb might not always reflect the default settings for an instance.

For a list of default settings, see the package defaults . Configure the external URL for GitLab To display the correct repository clone links to your users, you must provide GitLab with the URL your users use to reach the repository. You can use the IP of your server, but a Fully Qualified Domain Name (FQDN) is preferred. See the DNS documentation for more details about the use of DNS in a GitLab Self-Managed instance.

To change the external URL: Optional. Before you change the external URL, determine if you have previously defined a custom Home page URL or After sign-out path . Both of these settings might cause unintentional redirecting after configuring a new external URL. If you have defined any URLs, remove them completely. Edit /etc/gitlab/gitlab.rb and change external_url to your preferred URL: ruby external_url "http://gitlab.example.com" Alternatively, you can use the IP address of your server: ruby external_url "http://10.0.0.1" In the previous examples we use plain HTTP.

If you want to use HTTPS, see how to configure SSL . Reconfigure GitLab: shell sudo gitlab-ctl reconfigure Optional. If you had been using GitLab for a while, after you change the external URL, you should also invalidate the Markdown cache . Specify the external URL at the time of installation If you use the Linux package, you can set up your GitLab instance with the minimum number of commands by using the EXTERNAL_URL environment variable.

If this variable is set, it is automatically detected and its value is written as external_url in the gitlab.rb file. The EXTERNAL_URL environment variable affects only the installation and upgrade of packages. For regular reconfigure runs, the value in /etc/gitlab/gitlab.rb is used. As part of package updates, if you have EXTERNAL_URL variable set inadvertently, it replaces the existing value in /etc/gitlab/gitlab.rb without any warning.

So, we recommended not to set the variable globally, but rather pass it specifically to the installation command: shell sudo EXTERNAL_URL = "https://gitlab.example.com" apt-get install gitlab-ee Configure a relative URL for GitLab Status : Beta Configuring a relative URL for GitLab has known issues with Geo and testing limitations . While we recommended installing GitLab in its own (sub)domain, sometimes it is not possible.

In that case, GitLab can also be installed under a relative URL, for example, https://example.com/gitlab . By changing the URL, all remote URLs change as well, so you must manually edit them in any local repository that points to your GitLab instance. These instructions are for Linux package installations. For instructions for self-compiled (source) installations, see install GitLab under a relative URL . To enable relative URL in GitLab: Set the external_url in /etc/gitlab/gitlab.rb : ruby external_url "https://example.com/gitlab" In this example, the relative URL under which GitLab is served is /gitlab .

Change it to your liking. Reconfigure GitLab: shell sudo gitlab-ctl reconfigure If you have any issues, see the troubleshooting section . Load external configuration file from non-root user Linux package installations load all configuration from /etc/gitlab/gitlab.rb file. This file has strict file permissions and is owned by the root user. The reason for strict permissions and ownership is that /etc/gitlab/gitlab.rb is being executed as Ruby code by the root user during gitlab-ctl reconfigure .

This means that users who have write access to /etc/gitlab/gitlab.rb can add a configuration that is executed as code by root . In certain organizations, it is allowed to have access to the configuration files but not as the root user. You can include an external configuration file inside /etc/gitlab/gitlab.rb by specifying the path to the file: Edit /etc/gitlab/gitlab.rb : ruby from_file "/home/admin/external_gitlab.rb" Reconfigure GitLab: shell sudo gitlab-ctl reconfigure When you use from_file : Code you include into /etc/gitlab/gitlab.rb using from_file runs with root privileges when you reconfigure GitLab.

Any configuration that is set in /etc/gitlab/gitlab.rb after from_file is included, takes precedence over the configuration from the included file. Read certificate from file Certificates can be stored as separate files and loaded into memory when running sudo gitlab-ctl reconfigure . Files containing certificates must be plaintext. In this example, the PostgreSQL server certificate is read directly from a file rather than copying and pasting into /etc/gitlab/gitlab.rb directly. ruby postgresql [ 'internal_certificate' ] = File . read ( '/path/to/server.crt' ) Migrating from git_data_dirs Starting in 18.0, git_data_dirs will no longer be a supported means of configuring Gitaly storage locations.

If you explicitly define git_data_dirs , you’ll need to migrate the configuration. For example, for the Gitaly service, if your /etc/gitlab/gitlab.rb configuration is as follows: ruby git_data_dirs ({ "default" => { "path" => "/mnt/nas/git-data" } }) you’ll need to redefine the configuration under gitaly['configuration'] instead. Note that the /repositories suffix must be appended to the path because it was previously appended internally. ruby gitaly [ 'configuration' ] = { storage : [ { name : 'default' , path : '/mnt/nas/git-data/repositories' , }, ] , } It’s important to note that the parent directory of the path must also be managed by Omnibus.

Following the example above, Omnibus must modify the permissions of /mnt/nas/git-data on reconfiguration and may store data in that directory during runtime. You should select an appropriate path that allows for this behavior. For Rails and Sidekiq clients, if your /etc/gitlab/gitlab.rb configuration is as follows: ruby git_data_dirs ({ "default" => { "gitaly_address" => "tcp://gitaly1.internal:8075" } }) You’ll need to redefine the configuration under gitlab_rails['repositories_storages'] instead: ruby gitlab_rails [ 'repositories_storages' ] = { "default" => { "gitaly_address" => "tcp://gitaly1.internal:8075" } } Store Git data in an alternative directory By default, Linux package installations store the Git repository data under /var/opt/gitlab/git-data/repositories , and the Gitaly service listens on unix:/var/opt/gitlab/gitaly/gitaly.socket .

To change the location of the directory, Edit /etc/gitlab/gitlab.rb : ruby gitaly [ 'configuration' ] = { storage : [ { name : 'default' , path : '/mnt/nas/git-data/repositories' , }, ] , } You can also add more than one Git data directory: ruby gitaly [ 'configuration' ] = { storage : [ { name : 'default' , path : '/var/opt/gitlab/git-data/repositories' , }, { name : 'alternative' , path : '/mnt/nas/git-data/repositories' , }, ] , } Reconfigure GitLab: shell sudo gitlab-ctl reconfigure Optional.

If you already have existing Git repositories in /var/opt/gitlab/git-data , you can move them to the new location: Prevent users from writing to the repositories while you move them: shell sudo gitlab-ctl stop Sync the repositories to the new location. Note there is no slash behind repositories , but there is a slash behind git-data : shell sudo rsync -av --delete /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/ Reconfigure to start the necessary processes and fix any wrong permissions: shell sudo gitlab-ctl reconfigure Double-check the directory layout in /mnt/nas/git-data/ .

The expected output should be repositories : shell sudo ls /mnt/nas/git-data/ Start GitLab and verify that you can browse through the repositor

The rest of this page is on the live site.