Configuration options for the GitLab Linux package

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.

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 self-managed GitLab instance.

To change the external URL:

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

  2. Edit /etc/gitlab/gitlab.rb:

    external_url "http://gitlab.example.com"

  3. Reconfigure GitLab:

    sudo gitlab-ctl reconfigure

  4. After you change the external URL, we recommended you also invalidate the Markdown cache.

Specify the external URL at the time of installation

If you use the GitLab 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:

sudo EXTERNAL_URL="https://gitlab.example.com" apt-get install gitlab-ee

Configure a relative URL for GitLab

note
For installations from source, there is a separate document.

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.

To enable relative URL in GitLab:

  1. Set the external_url in /etc/gitlab/gitlab.rb:

    external_url "https://example.com/gitlab"

    In this example, the relative URL under which GitLab is served is /gitlab. Change it to your liking.

  2. Reconfigure GitLab:

    sudo gitlab-ctl reconfigure

If you have any issues, see the troubleshooting section.

Load external configuration file from non-root user

Omnibus GitLab package loads 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 to write access to /etc/gitlab/gitlab.rb can add 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:

from_file "/home/admin/external_gitlab.rb"

Code you include into /etc/gitlab/gitlab.rb using from_file runs with root privileges when you run sudo gitlab-ctl reconfigure. Any configuration that is set in /etc/gitlab/gitlab.rb after from_file is included, takes precedence over the configuration from the included file.

Store Git data in an alternative directory

By default, Omnibus GitLab stores the Git repository data under /var/opt/gitlab/git-data. The repositories are stored in a subfolder called repositories.

To change the location of the git-data parent directory:

  1. Edit /etc/gitlab/gitlab.rb:

    git_data_dirs({ "default" => { "path" => "/mnt/nas/git-data" } })

    You can also add more than one Git data directories:

    git_data_dirs({
  "default" => { "path" => "/var/opt/gitlab/git-data" },
  "alternative" => { "path" => "/mnt/nas/git-data" }
})

    The target directories and any of its subpaths must not be a symlink.

  2. Reconfigure GitLab:

    sudo gitlab-ctl reconfigure

  3. Optional. If you already have existing Git repositories in /var/opt/gitlab/git-data, you can move them to the new location:

    1. Prevent users from writing to the repositories while you move them:

      sudo gitlab-ctl stop

    2. Sync the repositories to the new location. Note there is no slash behind repositories, but there is a slash behind git-data:

      sudo rsync -av --delete /var/opt/gitlab/git-data/repositories /mnt/nas/git-data/

    3. Reconfigure to start the necessary processes and fix any wrong permissions:

      sudo gitlab-ctl reconfigure

    4. Double-check the directory layout in /mnt/nas/git-data/. The expected output should be repositories:

      sudo ls /mnt/nas/git-data/

    5. Start GitLab and verify that you can browse through the repositories in the web interface:

      sudo gitlab-ctl start

If you’re running Gitaly on its own server remember to also include the gitaly_address for each Git data directory. See the documentation on configuring Gitaly.

If you’re not looking to move all repositories, but instead want to move specific projects between existing repository storages, use the Edit Project API endpoint and specify the repository_storage attribute.

Change the name of the Git user or group

note
We do not recommend changing the user or group of an existing installation because it can cause unpredictable side-effects.

By default, Omnibus GitLab uses the user name git for Git GitLab Shell login, ownership of the Git data itself, and SSH URL generation on the web interface. Similarly, the git group is used for group ownership of the Git data.

To change the user and group:

  1. Edit /etc/gitlab/gitlab.rb:

    user['username'] = "gitlab"
user['group'] = "gitlab"

  2. Reconfigure GitLab:

    sudo gitlab-ctl reconfigure

If you are changing the username of an existing installation, the reconfigure run doesn’t change the ownership of the nested directories, so you must do that manually. Make sure that the new user can access the repositories and uploads directories.

Specify numeric user and group identifiers

Omnibus GitLab creates users for GitLab, PostgreSQL, Redis, NGINX, etc. To specify the numeric identifiers for these users:

  1. Edit /etc/gitlab/gitlab.rb:

    user['uid'] = 1234
user['gid'] = 1234
postgresql['uid'] = 1235
postgresql['gid'] = 1235
redis['uid'] = 1236
redis['gid'] = 1236
web_server['uid'] = 1237
web_server['gid'] = 1237
registry['uid'] = 1238
registry['gid'] = 1238
mattermost['uid'] = 1239
mattermost['gid'] = 1239
prometheus['uid'] = 1240
prometheus['gid'] = 1240

  2. Reconfigure GitLab:

    sudo gitlab-ctl reconfigure

  3. Optional. If you’re changing user['uid'] and user['gid'], make sure to update the uid/guid of any files not managed by Omnibus directly, for example the logs:

find /var/log/gitlab -uid <old_uid> | xargs -I:: chown git ::
find /var/log/gitlab -gid <old_uid> | xargs -I:: chgrp git ::
find /var/opt/gitlab -uid <old_uid> | xargs -I:: chown git ::
find /var/opt/gitlab -gid <old_uid> | xargs -I:: chgrp git ::

Disable user and group account management

By default, Omnibus GitLab creates system user and group accounts, as well as keeping the information updated. These system accounts run various components of the package. Most users don’t need to change this behavior. However, if your system accounts are managed by other software, for example LDAP, you might need to disable account management done by the GitLab package.

By default, the Omnibus GitLab package expects that following users and groups to exist:

Linux user and group Required Description
git Yes GitLab user/group
gitlab-www Yes Web server user/group
gitlab-redis Only when using the packaged Redis Redis user/group for GitLab
gitlab-psql Only when using the packaged PostgreSQL PostgreSQL user/group
gitlab-prometheus Yes Prometheus user/group for Prometheus monitoring and various exporters
mattermost Only when using GitLab Mattermost GitLab Mattermost user/group
registry Only when using GitLab Registry GitLab Registry user/group
gitlab-consul Only when using GitLab Consul GitLab Consul user/group

To disable user and group accounts management:

  1. Edit /etc/gitlab/gitlab.rb: