How to Run GitLab with Self-Signed SSL Certificate

Update 19th Sept 2014: We added a reference to the GitLab Omnibus Readme as additional resources at the bottom of this post.


This post describes how to configure a running GitLab instance with a (self-signed) SSL certificate. The following steps assume you already have a running instance of GitLab available. Ok, let's start with the generation of your SSL certificate.

nginx Series Overview

Generate Your Certificate

Before changing any GitLab configuration, you need a valid SSL certificate. In case you already bought a certificate from a certificate authority, you can go straight ahead to the next section. Else, you probably need to generate your own certificate. When using a self-signed certificate browsers will show a message that the page you're visiting cannot be trusted. Make sure everybody who'll access the GitLab url knows this.

In order to generate the certificate, we use Ubuntu and OpenSSL. If you don't already have OpenSSL installed, please do so. Additionally, the following steps assume you're using nginx as webserver. The following commands describe the steps to generate your certificate. If you need further information, please find them in the SSL Certificates post on Servers for Hackers.

# Create a 2048 bit private key
# If the ssl directory doesn't exist, please create it first
sudo openssl genrsa -out "/etc/nginx/ssl/gitlab.key" 2048

# This command generates the certificate signing request
sudo openssl req -new -key "/etc/nginx/ssl/gitlab.key" -out "/etc/nginx/ssl/gitlab.csr"  

You'll be asked a lot of questions now.

    Country Name (2 letter code) [AU]:DE
State or Province Name (full name) [Some-State]:Saxony-Anhalt  
Locality Name (eg, city) []:Magdeburg  
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Future Studio  
Organizational Unit Name (eg, section) []:  
Common Name (e.g. server FQDN or YOUR name) []:gitlab.yourdomain.com  
Email Address []:

Please enter the following 'extra' attributes  
to be sent with your certificate request  
A challenge password []:  
An optional company name []:  

The code above has examples in the fields which you should fill for your certificate. Please set the Common Name/FQDN to the url you're running GitLab. If you run your GitLab instance on git.yourdomain.com, please your git.yourdomain.com as FQDN!

Now you can finish this up and create the signed certificate:

sudo openssl x509 -req -days 365 -in "/etc/nginx/ssl/gitlab.csr" -signkey "/etc/nginx/ssl/gitlab.key"  -out "/etc/nginx/ssl/gitlab.crt"  

This certificate is valid for one year (365 days).

Configure Nginx

The GitLab project provides a very useful and handy nginx configuration file. This can be used with some adjustments. Please copy the contents of the GitLab nginx configuration file to your nginx configuration file.

Update the following lines:

# If you didn't install GitLab to the default path, update the line below to the path to your gitlab.socket
server unix:/home/git/gitlab/tmp/sockets/gitlab.socket;  
# your domain must be specified here; this is also the domain you chose for certificate FQDN
server_name git.example.com

# specify the path to your certificate .crt and .key files
ssl_certificate /etc/nginx/ssl/gitlab.crt;  
ssl_certificate_key /etc/nginx/ssl/gitlab.key;

# Remove the files below from the nginx configuration
# ---
## Enable OCSP stapling to reduce the overhead and latency of running SSL.
## Replace with your ssl_trusted_certificate. For more info see:
## - https://medium.com/devops-programming/4445f4862461
## - https://www.ruby-forum.com/topic/4419319
ssl_stapling on;  
ssl_stapling_verify on;  
ssl_trusted_certificate /etc/nginx/ssl/stapling.trusted.crt;  
resolver 208.67.222.222 208.67.222.220 valid=300s;  
resolver_timeout 10s;  

Configure GitLab

Before changing the configuration of GitLab, stop the running instance.

sudo service gitlab stop  

Now, navigate to your GitLab installation directory, default is /home/git/gitlab. Use your favorite editor and open config/gitlab.yml configuration file. Change the port to 443 and set https to true.

If you're having trouble with Gravatar and the profile pictures cannot be resolved correctly, please disable Gravatar support as well.

Configure GitLab-Shell

The GitLab-Shell is responsible for any git interaction. You need to update the configuration to the new HTTPS settings. Navigate to the GitLab-Shell directory, default is home/git/gitlab-shell. Open the config.yml with your favorite editor and change the gitlab_url to use https:// over http://. When using a self-signed certificate, you also have to set self_signed_cert to true.

Restart GitLab and Nginx

The configuration is done. Restart GitLab and Nginx

sudo service gitlab start  
sudo service nginx restart  

Please make sure everything is running properly. Run the provided checks for GitLab and keep an eye on Check GitLab API access and it is OK. Else the configuration is not correct and you have to recheck the previously described steps. To run the checks, navigate to the GitLab directory (default is /home/git/gitlab) and run the following command.

sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production  

You're done. Go to your domain and check if Gitlab is running. You'll probably get the warning regarding insecure certificates in case of self-signed certificate usage.


Additional Resources

Explore the Library

Find interesting tutorials and solutions for your problems.