- Available SSL Configuration Tasks
- Host Services
- Connecting to External Resources
-
Troubleshooting
- Useful OpenSSL Debugging Commands
- Common SSL errors
- Git-LFS and other embedded services written in golang report custom certificate signed by unknown authority
- Reconfigure Fails Due to Certificates
- Custom Certificates Missing or Skipped
- Custom certificates not detected
- Let’s Encrypt Certificate signed by unknown authority
- Let’s Encrypt fails on reconfigure
- Additional troubleshooting
- Details on how GitLab and SSL work
SSL Configuration
Available SSL Configuration Tasks
Omnibus-GitLab supports several common use cases for SSL configuration.
- Allow
https
connections to GitLab instance services - 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
- 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.
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
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.
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"
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
letsencrypt['enable'] = false
in /etc/gitlab/gitlab.rb
to disable integration. Otherwise the certificate
could be overwritten due to the 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:
-
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
-
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.
Install Custom Public Certificates
c_rehash
dependency to properly symlink the certificates.
Perl is currently not bundled in Omnibus GitLab.- Generate the PEM or DER encoded public certificate from your private key certificate.
-
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 ishttps://gitlab.example.com
, the certificate should be namedgitlab.example.com.crt
.To specify a different path and file name, you can change the default SSL certificate location.
- Enable and manually configure HTTPS on NGINX to set up GitLab to use your own certificates.
-
Reconfigure GitLab:
sudo gitlab-ctl reconfigure
/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.