SSL Configuration

Available SSL Configuration Tasks

Omnibus-GitLab supports several common use cases for SSL configuration.

  1. Allow https connections to GitLab instance services
  2. Configure public certificate bundles for external resource connections

Host Services

Administrators can enable secure http using any method supported by a GitLab service.

Service Manual SSL Let’s Encrypt
Primary GitLab Instance Domain Yes Yes
Container Registry Yes Yes
Mattermost Yes Yes
GitLab Pages Yes No

Let’s Encrypt Integration

GitLab can be integrated with Let’s Encrypt.

Primary GitLab Instance

Version history
  • Introduced in GitLab 10.5 and disabled by default.
  • Enabled by default in GitLab 10.7 and later if external_url is set with the https protocol and no certificates are configured.
note
In order for Let’s Encrypt verification to work automatically, ports 80 and 443 will need to be accessible to the public Let’s Encrypt servers that run the validation checks. The validation does not work with non-standard ports. If the environment is private or air-gapped, certbot provides a manual method to generate certificates for custom installation.
caution
Administrators installing or upgrading to GitLab 10.7 or later and do not plan on using Let’s Encrypt should set letsencrypt['enable'] = false in /etc/gitlab/gitlab.rb to disable.

Add the following entries to /etc/gitlab/gitlab.rb to enable Let’s Encrypt support for the primary domain:

letsencrypt['enable'] = true                      # GitLab 10.5 and 10.6 require this option
external_url "https://gitlab.example.com"         # Must use https protocol
letsencrypt['contact_emails'] = ['foo@email.com'] # Optional
note
Certificates issued by Let’s Encrypt expire every ninety days. The optional contact_emails setting causes an expiration alert to be sent to the configured address when that expiration date approaches.

GitLab Components

Introduced in GitLab 11.0.

Follow the steps to enable basic Let’s Encrypt integration and modify /etc/gitlab/gitlab.rb with any of the following that apply:

registry_external_url "https://registry.example.com"     # container registry, must use https protocol
mattermost_external_url "https://mattermost.example.com" # mattermost, must use https protocol
#registry_nginx['ssl_certificate'] = "path/to/cert"      # Must be absent or commented out

The Let’s Encrypt certificate is created with the GitLab primary instance as the primary name on the certificate. Additional services such as the registry are added as alternate names to the same certificate. Note in the example above, the primary domain is gitlab.example.com and the registry domain is registry.example.com. Administrators do not need to worry about setting up wildcard certificates.

Automatic Let’s Encrypt Renewal

Introduced in GitLab 10.7.

caution
Administrators installing or upgrading to GitLab 12.1 or later and plan on using their own Let’s Encrypt certificate should set letsencrypt['enable'] = false in /etc/gitlab/gitlab.rb to disable automatic renewal. Otherwise, a gitlab-ctl reconfigure may attempt to renew the certificates, and thus overwrite them.

Default installations schedule renewals after midnight on every 4th day. The minute is determined by the value in external_url to help distribute the load on the upstream Let's Encrypt servers.

Explicitly set renewal times by adding the following to /etc/gitlab/gitlab.rb:

# This example renews every 7th day at 12:30
letsencrypt['auto_renew_hour'] = "12"
letsencrypt['auto_renew_minute'] = "30"
letsencrypt['auto_renew_day_of_month'] = "*/7"
note
The certificate gets renewed only if it is going to expire in 30 days. For example, if you set it to renew on the 1st of every month at 00:00 and the certificate expires on the 31st, then the certificate will expire before getting renewed.

Disable automatic renewal with the following in /etc/gitlab/gitlab.rb:

letsencrypt['auto_renew'] = false

Manual Let’s Encrypt Renewal

Renew Let’s Encrypt certificates manually using one of the following commands:

sudo gitlab-ctl reconfigure
sudo gitlab-ctl renew-le-certs
caution
GitLab 12.1 or later will attempt to renew any Let’s Encrypt certificate. If you plan to use your own Let’s Encrypt certificate you must set letsencrypt['enable'] = false in /etc/gitlab/gitlab.rb to disable integration. Otherwise the certificate could be overwritten due to the renewal.
note
The above commands require root privileges and only generate a renewal if the certificate is close to expiration. Consider the upstream rate limits if encountering an error during renewal.

Use an ACME server other than Let’s Encrypt

You can use an ACME server other than Let’s Encrypt, and configure GitLab to use that to fetch a certificate. Some services that provide their own ACME server are:

To configure GitLab to use a custom ACME server:

  1. Edit /etc/gitlab/gitlab.rb and set the ACME endpoints:

    external_url 'https://example.com'
    letsencrypt['acme_staging_endpoint'] = 'https://ca.internal/acme/acme/directory'
    letsencrypt['acme_production_endpoint'] = 'https://ca.internal/acme/acme/directory'
    

    If the custom ACME server provides it, use a staging endpoint as well. Checking the staging endpoint first ensures that the ACME configuration is correct before submitting the request to ACME production. Do this to avoid ACME rate-limits while working on your configuration.

    The default values are:

    https://acme-staging-v02.api.letsencrypt.org/directory
    https://acme-v02.api.letsencrypt.org/directory
    
  2. Reconfigure GitLab:

    sudo gitlab-ctl reconfigure
    

Connecting to External Resources

Some environments connect to external resources for various tasks. Omnibus-GitLab allows these connections to use secure http (https).

Default Configuration

Omnibus-GitLab ships with the official CAcert.org collection of trusted root certification authorities which are used to verify certificate authenticity.

Other Certificate Authorities

Omnibus GitLab supports connections to external services with self-signed certificates.

note
Custom certificates were introduced in GitLab 8.9.
note
For installations that use self-signed certificates, Omnibus-GitLab provides a way to manage these certificates. For more technical details how this works, see the details at the bottom of this page.

Install Custom Public Certificates

note
A perl interpreter is required for c_rehash dependency to properly symlink the certificates. Perl is currently not bundled in Omnibus GitLab.
  1. Generate the PEM or DER encoded public certificate from your private key certificate.
  2. Copy the public certificate file only into the /etc/gitlab/trusted-certs directory. By default, GitLab expects to find a certificate titled after your GitLab URL with a .crt extension. For instance, if your server address is https://gitlab.example.com, the certificate should be named gitlab.example.com.crt.

    To specify a different path and file name, you can change the default SSL certificate location.

  3. Enable and manually configure HTTPS on NGINX to set up GitLab to use your own certificates.
  4. Reconfigure GitLab:

    sudo gitlab-ctl reconfigure
    
caution
If using a custom certificate chain, the root and/or intermediate certificates must be put into separate files in /etc/gitlab/trusted-certs due to c_rehash creating a hash for the first certificate only.

Troubleshooting

Useful OpenSSL Debugging Commands

Sometimes it’s helpful to get a better picture of the SSL certificate chain by viewing it directly at the source. These commands are part of the standard OpenSSL library of tools for diagnostics and debugging.