- Configure the external URL for GitLab
- Configure a relative URL for GitLab
- Load external configuration file from non-root user
- Store Git data in an alternative directory
- Change the name of the Git user or group
- Specify numeric user and group identifiers
- Disable user and group account management
- Move the home directory for a user
- Disable storage directories management
- Start Omnibus GitLab services only after a given file system is mounted
- Configure the runtime directory
- Configure a failed authentication ban
- Disable automatic cache cleaning during installation
- Error Reporting and Logging with Sentry
- Set a Content Delivery Network URL
- Set a Content Security Policy
- Set initial root password on installation
- Set allowed hosts to prevent host header attacks
- Related topics
- Troubleshooting
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:
-
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
:external_url "http://gitlab.example.com"
-
Reconfigure GitLab:
sudo gitlab-ctl reconfigure
-
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
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:
-
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. -
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:
-
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.
-
Reconfigure GitLab:
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:
sudo gitlab-ctl stop
-
Sync the repositories to the new location. Note there is no slash behind
repositories
, but there is a slash behindgit-data
: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:
sudo gitlab-ctl reconfigure
-
Double-check the directory layout in
/mnt/nas/git-data/
. The expected output should berepositories
:sudo ls /mnt/nas/git-data/
-
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
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:
-
Edit
/etc/gitlab/gitlab.rb
:user['username'] = "gitlab" user['group'] = "gitlab"
-
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:
-
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
-
Reconfigure GitLab:
sudo gitlab-ctl reconfigure
-
Optional. If you’re changing
user['uid']
anduser['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:
-
Edit
/etc/gitlab/gitlab.rb
: