Setting custom environment variables

If necessary you can set custom environment variables to be used by Puma, Sidekiq, Rails and Rake via /etc/gitlab/gitlab.rb. This can be useful in situations where you need to use a proxy to access the internet and need to clone externally hosted repositories directly into GitLab. In /etc/gitlab/gitlab.rb supply a gitlab_rails['env'] with a hash value. For example:

gitlab_rails['env'] = {
    "http_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080",
    "https_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080"
#    "no_proxy" => ".yourdomain.com"  # Wildcard syntax if you need your internal domain to bypass proxy. Do not specify a port.
}

You can also override environment variables from other GitLab components which might be required if you are behind a proxy:

# Needed for proxying Git clones
gitaly['env'] = {
    "http_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080",
    "https_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080"
}

gitlab_workhorse['env'] = {
    "http_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080",
    "https_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080"
}

gitlab_pages['env'] = {
    "http_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080",
    "https_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080"
}

# If you use the docker registry
registry['env'] = {
    "http_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080",
    "https_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080"
}

GitLab will attempt to use HTTP Basic Authentication when a username and password is included in the proxy URL.

Proxy settings use the . syntax for globing.

Proxy URL values should generally be http:// only, unless your proxy has its own SSL certificate and SSL enabled. This means, even for the https_proxy value, you should usually specify a value as http://<USERNAME>:<PASSWORD>@example.com:8080.

Applying the changes

Any change made to the environment variables requires a reconfigure for it to take effect.

Perform a reconfigure:

sudo gitlab-ctl reconfigure

Noteworthy environment variables

TMPDIR

Ruby and other components use the TMPDIR environment variable to determine where to store temporary files. By default, this is /tmp.

You may need to configure a custom temporary directory if:

• Your /tmp is mounted as tmpfs with limited space.
• Large files (such as LFS objects or CI artifacts) cause /tmp to fill up.
• Geo secondary sites run out of space in /tmp during object storage replication.

To configure a custom temporary directory:

1. Create the directory and set permissions:

   sudo mkdir -p /var/opt/gitlab/tmp
   sudo chown git:git /var/opt/gitlab/tmp
   sudo chmod 700 /var/opt/gitlab/tmp

2. Edit /etc/gitlab/gitlab.rb to set TMPDIR for both Rails and Workhorse:

   gitlab_rails['env'] = { 'TMPDIR' => '/var/opt/gitlab/tmp' }
   gitlab_workhorse['env'] = { 'TMPDIR' => '/var/opt/gitlab/tmp' }

   Both values must point to the same directory. When uploading CI/CD artifacts with object storage enabled, Workhorse generates a metadata file in its TMPDIR and passes the path to Rails. Rails validates that the file is in an allowed directory (which includes its own TMPDIR). If these values differ, artifact uploads fail with 400 Bad Request.

3. Reconfigure and restart GitLab:

   sudo gitlab-ctl reconfigure
   sudo gitlab-ctl restart

4. Verify the setting:

   sudo gitlab-rails runner "puts ENV['TMPDIR']"

   The output should display your configured path.

Troubleshooting

An environment variable is not being set

Check that you don’t have multiple entries for the same ['env']. The last one will override previous entries. In this example, NTP_HOST will not be set:

gitlab_rails['env'] = { 'NTP_HOST' => "<DOMAIN_OF_NTP_SERVICE>" }

gitlab_rails['env'] = {
    "http_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080",
    "https_proxy" => "http://<USERNAME>:<PASSWORD>@example.com:8080"
}

CI/CD artifact uploads fail with 400 Bad Request after changing TMPDIR

If CI/CD artifact uploads return 400 Bad Request with Content-Type: text/plain after configuring a custom TMPDIR, the most likely cause is a mismatch between the TMPDIR values for Rails and Workhorse.

To resolve this:

1. Ensure both values match in /etc/gitlab/gitlab.rb:

   gitlab_rails['env'] = { 'TMPDIR' => '/var/opt/gitlab/tmp' }
   gitlab_workhorse['env'] = { 'TMPDIR' => '/var/opt/gitlab/tmp' }

2. Reconfigure GitLab:

   sudo gitlab-ctl reconfigure

You can confirm the mismatch by checking Workhorse logs for the failing correlation ID. Look for metadata.gz entries with local_temp_path pointing to a different directory than your configured TMPDIR.

Error: Connection reset by peer when mirroring repositories

If the no_proxy value includes port numbers in the URLs, it may cause DNS resolution failures. Remove any port numbers from the no_proxy URLs to resolve this issue.