How to setup Let’s Encrypt for Gitlab

This information is outdated as of 2019, but I’ll leave it up here for future reference.

This is a quick guide to setting up Let’s Encrypt for Gitlab

Assumptions made:

  1. You’re using the Omnibus Gitlab install.
  2. You’re using Ubuntu (or Debian).
  3. Gitlab is available on the root of a subdomain (

Install git if you don’t have it already:

sudo apt-get install git

Install Let’s Encrypt:

mkdir letsencrypt
cd letsencrypt
git clone

Make a Let’s Encrypt config file.

touch gitlab.ini
nano gitlab.ini

Use this as a starting point:

#this is the let's Encrypt config for our gitlab instance

# use the webroot authenticator.
authenticator = webroot
# the following path needs to be served by our webserver
# to validate our domains
 webroot-path = /var/www/letsencrypt

# generate certificates for the specified domains.
domains =

# register certs with the following email address
email = [email protected]

# use a 4096 bit RSA key instead of 2048
rsa-key-size = 4096



You should make the webroot too:

sudo mkdir /var/www/letsencrypt

Now, you’ll need to set a few things up before you can switch Gitlab over to HTTPS. First you need to add an alias to Gitlab’s nginx config to allow the LE verification to take place.

Edit your gitlab.rb file:

sudo nano /etc/gitlab/gitlab.rb

Add the following two lines near the top, I added them after the ‘external_url’ line (you already have that set, right?!).

nginx['custom_gitlab_server_config']="location ^~ /.well-known {\n alias /var/www/letsencrypt/.well-known;\n}\n"
nginx['custom_gitlab_mattermost_server_config']="location ^~ /.well-known {\n alias /var/www/letsencrypt/.well-known;\n}\n"

Now you need to tell gitlab to check the updated config file and update itself:

sudo gitlab-ctl reconfigure

Since all that’s changed is the nginx config, the reconfigure process should be real quick. Once it’s done, you can actually run Let’s Encrypt.

sudo ./letsencrypt-auto certonly --config gitlab.ini

This will download some additional packages and python libraries, then add a small file(.well-known) in /var/www/letsencrypt/ that the LE servers will then check for. Thanks to the above change to Gitlab, it’s passing that file through so you can have the online check and still use Gitlab at the same time (no downtime).

I originally did this setup without the “agree-tos” line in the config, so there were some interactive steps, but in theory the process should run without interaction if you have that in place and this is a first attempt.

Once it is complete your certs are available in “/etc/letsencrypt/live/”

Reopen your /etc/gitlab/gitlab.rb file again and add the following lines to tell Gitlab(nginx) where the cert files are:

nginx['redirect_http_to_https'] = true
nginx['ssl_certificate']= "/etc/letsencrypt/live/"
nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/"

Also make sure to edit your external_url to be https now as well:

external_url ''

The top of your gitlab.rb should look something like this now:

# Url on which GitLab will be reachable.
## For more details on configuring external_url see:
external_url ''

nginx['redirect_http_to_https'] = true
nginx['ssl_certificate']= "/etc/letsencrypt/live/"
nginx['ssl_certificate_key'] = "/etc/letsencrypt/live/"

nginx['custom_gitlab_server_config']="location ^~ /.well-known {\n alias /var/www/letsencrypt/.well-known;\n}\n"
nginx['custom_gitlab_mattermost_server_config']="location ^~ /.well-known {\n alias /var/www/letsencrypt/.well-known;\n}\n"


That’s it, you should be all set. If you really want to automate it entirely, add “renew-by-default” to your config, then setup a cronjob to fire periodically:

crontab -e
@monthly /path/to/letsencrypt/letsencrypt-auto certonly --config /path/to/letsencrypt/gitlab.ini && gitlab-ctl restart nginx


Leave a Comment

NOTE - You can use these HTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>