Gitaly TLS support

Gitaly supports TLS encryption. To communicate with a Gitaly instance that listens for secure connections, use the tls:// URL scheme in the gitaly_address of the corresponding storage entry in the GitLab configuration.

Gitaly provides the same server certificates as client certificates in TLS connections to GitLab. This can be used as part of a mutual TLS authentication strategy when combined with reverse proxies (for example, NGINX) that validate client certificate to grant access to GitLab.

You must supply your own certificates as this isn’t provided automatically. The certificate corresponding to each Gitaly server must be installed on that Gitaly server.

Additionally, the certificate (or its certificate authority) must be installed on all:

  • Gitaly servers.
  • Gitaly clients that communicate with it.

If you use a load balancer, it must be able to negotiate HTTP/2 using the ALPN TLS extension.

Certificate requirements

  • The certificate must specify the address you use to access the Gitaly server. You must add the hostname or IP address as a Subject Alternative Name to the certificate.
  • You can configure Gitaly servers with both an unencrypted listening address listen_addr and an encrypted listening address tls_listen_addr at the same time. This allows you to gradually transition from unencrypted to encrypted traffic if necessary.
  • The certificate’s Common Name field is ignored.

Configure Gitaly with TLS

Configure Gitaly before configuring TLS support.

The process for configuring TLS support depends on your installation type.

  1. Create certificates for Gitaly servers.
  2. On the Gitaly clients, copy the certificates (or their certificate authority) into /etc/gitlab/trusted-certs:

    sudo cp cert.pem /etc/gitlab/trusted-certs/
    
  3. On the Gitaly clients, edit gitlab_rails['repositories_storages'] in /etc/gitlab/gitlab.rb as follows:

    gitlab_rails['repositories_storages'] = {
      'default' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' },
      'storage1' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' },
      'storage2' => { 'gitaly_address' => 'tls://gitaly2.internal:9999' },
    }
    
  4. Save the file and reconfigure GitLab.
  5. On the Gitaly servers, create the /etc/gitlab/ssl directory and copy your key and certificate there:

    sudo mkdir -p /etc/gitlab/ssl
    sudo chmod 755 /etc/gitlab/ssl
    sudo cp key.pem cert.pem /etc/gitlab/ssl/
    sudo chmod 644 /etc/gitlab/ssl/cert.pem
    sudo chmod 600 /etc/gitlab/ssl/key.pem
    # For Linux package installations, 'git' is the default username. Modify the following command if it was changed from the default
    sudo chown -R git /etc/gitlab/ssl
    
  6. Copy all Gitaly server certificates (or their certificate authority) to /etc/gitlab/trusted-certs on all Gitaly servers and clients so that Gitaly servers and clients trust the certificate when calling into themselves or other Gitaly servers:

    sudo cp cert1.pem cert2.pem /etc/gitlab/trusted-certs/
    
  7. Edit /etc/gitlab/gitlab.rb and add:

    gitaly['configuration'] = {
       # ...
       tls_listen_addr: '0.0.0.0:9999',
       tls: {
         certificate_path: '/etc/gitlab/ssl/cert.pem',
         key_path: '/etc/gitlab/ssl/key.pem',
       },
    }
    
  8. Save the file and reconfigure GitLab.
  9. Run sudo gitlab-rake gitlab:gitaly:check on the Gitaly client (for example, the Rails application) to confirm it can connect to Gitaly servers.
  10. Verify Gitaly traffic is being served over TLS by observing the types of Gitaly connections.
  11. Optional. Improve security by:
    1. Disabling non-TLS connections by commenting out or deleting gitaly['configuration'][:listen_addr] in /etc/gitlab/gitlab.rb.
    2. Saving the file.
    3. Reconfiguring GitLab.

Update the certificates

To update the Gitaly certificates after initial configuration:

If the content of your SSL certificates under the /etc/gitlab/ssl directory have been updated, but no configuration changes have been made to /etc/gitlab/gitlab.rb, then reconfiguring GitLab doesn’t affect Gitaly. Instead, you must restart Gitaly manually for the certificates to be loaded by the Gitaly process:

sudo gitlab-ctl restart gitaly

If you change or update the certificates in /etc/gitlab/trusted-certs without making changes to the /etc/gitlab/gitlab.rb file, you must:

  1. Reconfigure GitLab so the symlinks for the trusted certificates are updated.
  2. Restart Gitaly manually for the certificates to be loaded by the Gitaly process:

    sudo gitlab-ctl restart gitaly
    

Observe type of Gitaly connections

For information on observing the type of Gitaly connections being served, see the relevant documentation.