Add a custom namecheap domain for gitlab pages

Creating the custom domain on Gitlab Pages

After opening the Deploy > Pages section in the Gitlab panel, you will need to press the New Domain button.

This would redirect you to the New Pages domain view.

Add your domain name there for example qa-log.com, and switch off the Automatic certificate management option. We will handle the SSL later.

Press on Create New Domain and after that, we are presented with the Pages Domain view that gives us some information on the information on how to configure the DNS record.

I found the data there to be a little bit misleading, as in the DNS section it was saying that I should use ALIAS for the DNS configuration, but in the gitlab docs for custom pages it is saying that for root domain you need to configure an A record instead.

Regardless, we need to add the DNS records and verify the ownership of your domain.

Configuring Namecheap root domain

After you buy a Namecheap domain, you can open the Dashboard and over there head over to the Domain List section, and press on the Manage button.

After that go to Advanced DNS and make sure that you don’t have any DNS records over there that might collide.

Now you need to add the A record to point to the Gitlab servers, and the TXT record with the information that Gitlab was providing.

⚠️ Warning: When adding the A record in the host section add @ and not your domain example.com. Gitlab docs mislead me into believing that I should add the domain but for Namecheap, we need to use @ as described in this namecheap blog

⚠️ Warning: For the TXT record for verifying the ownership you need to omit the DOMAIN at the end of hostname. For example _gitlab-pages-verification-code.example.com is bad and it won’t work as it contains .example.com at the end. It should be only _gitlab-pages-verification-code in the host section. This is also written in the namecheap blog

Save the configuration and wait until the domain gets validated on Gitlab.

Once it is validated save the domain, and you can visit your site on http://DOMAIN and you should see it there. Note that it might take around one hour until the DNS is properly updated

Troubleshoot not loading page

In case the page is not loading you can do a DNS lookup and check if the DNS was configured properly.

One such tool that can be used is called dig which will do a DNS lookup and you can check if the A tag has been correctly configured.

A correctly configured DNS would display such information when we run dig on it:

$ dig example.com A
example.com. 1653   IN  A   35.185.44.232

Otherwise, we might get a SOA response as seen below:

$ dig examplefjeiii.com A
AUTHORITY SECTION
com. 900    IN  SOA  a.gtld-servers.net   .....

Enable HTTPS on your page

Now that we have the page running with HTTP we could make it more secure by running it using HTTPS.

Thankfully Gitlab makes this process very easy if we would like to use the automatic certificate management using Let’s Encrypt

What we need to do is to click on Edit for our domain in the GitLab Deploy > Pages section, and after that, we toggle the Automatic certificate management using the Let’s Encrypt option.

Issuing the certificate and updating the Pages configuration can take up to an hour, but after that, the page should be using HTTPS and will be accessible with the https:// prefix