Adding TLS to a Custom Domain on GitLab Pages

This tutorial assumes you've already purchased an SSL certificate on Namecheap and want to associate it with a domain record you host there as well. It also documents how to issue the certificate and install it on GitLab.

How to Issue Certificate on Namecheap

  1. Sign in to Namecheap.
  2. Go toĀ https://ap.www.namecheap.com/ProductList/SslCertificates
  3. Find your certificate and click "Activate".
  4. Namecheap will walk you through each step required for activating your certificate.
  5. Generate a CSR.
    1. Namecheap offers instructions for generating the CSR on the page where you will complete this step.
    2. Namecheapā€™s recommended openssl command looks like this:
      openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr
    3. I choose to do this:
      openssl req -new -newkey rsa:4098 -nodes -keyout example_com.key -out example_com.csr
    4. Once you've executed the command, and answered all its questions, you should have an example_com.keyĀ and an example_com.csr file
  6. If youā€™re on an Apple machine, you can copy the content of your certificate signing request (csr) file into your buffer with this command:Ā pbcopy < example.com_csr.
    1. Supposedly you can useĀ xselĀ to do the same on Linux. I canā€™t confirm becauseā€”for the first time in my computer-owning lifeā€”I donā€™t have a Linux machine with a GUI handy.
  7. When you paste the content of yourĀ example_com.csrĀ file into the Namecheap UI, it will pull out the domain name that corresponds.
  8. Click the "Next" button.
  9. Click "Next" again.
  10. The next page asks you for your preferred method of Domain Control Validation (DCV). I recommend you select "Email".
    1. The other two methods (DNS and HTTP) supposedly work, but I didn't have luck with the DNS method despite being more familiar with it. I waited a half hour before contacting support. They were exceedingly helpful, but strongly encouraged me to use the email method, so I never took the time to learn the other methods.
    2. If you have Whoisguard activated (which is on by default now), then the whoisguard email is likely the one you want to use to confirm domain ownership.
  11. Click "Submit"
  12. You will receive an email at the address associated with your DNS record.
    1. Be sure to check your spam folder.
  13. The instructions in the email should be fairly straightforward, but they will likely be different depending on which certificate authority issues yours.
    1. My email amounted to me copying a string of garbledy gook into my clipboard, clicking a link, and pasting the text into the first textbox on the screen.
  14. Go toĀ the domain list.
  15. Click "Manage" for the domain you associated with the TLS certificate.
  16. Click the "Products" tab.
  17. Click the "Manage" button next to the TLS certificate.
  18. In the table titled "Certificate Versions", you should see an item in the first row that says "Issued". Click the "down arrow" to the right of "See Details".
  19. Click "Download Certificate".
  20. When you unzip the certificate file, it should look like this:
    artburkart$ unzip example_com.zip
    Archive:  example_com.zip
      inflating: example_com.crt
      inflating: example_com.ca-bundle
      inflating: example_com.p7b

How to Use Your SSL Certificate on GitLab Pages

The instructions for setting up TLS on a GitLab Pages projectĀ can be found on their websiteĀ couched inside instructions for how to generate a certificate with LetsEncrypt. It's probably worth mentioning that LetsEncrypt is an awesome alternative to purchasing an SSL certificate. Currently, it requires a little more work, more frequently (every 90 days) than purchasing a certificate, but definitely a strong option.

  1. Go toĀ gitlab.com.
  2. Click on your GitLab Pages project.
  3. Hover your mouse over "Settings" on the left side.
  4. Click "Pages".
  5. Click "New Domain".
    1. Type in your domain (i.e., example.com) into the first textbox.
    2. This is the part that tripped me up. You want to convert theĀ p7bĀ file into a valid PEM file for Gitlab. The commands can beĀ found on Namecheapā€™s website:
      openssl pkcs7 -print_certs -in example_com.p7b -out example_com.pem
    3. Copy the content of theĀ example_com.pemĀ file into the textbox labeled "Certificate".
    4. Copy the content of theĀ example_com.keyĀ file into the textbox labeled "Key".
  6. Click "Create New Domain".

If youā€™ve done everything correctly, GitLab should reward you with a statement saying that your ā€œDomain was createdā€.

Happy blogging or whatever you do with your static website!Ā šŸ˜„

This article was updated on 22 November 2018