How to add a custom subdomain to GitLab Pages with Namecheap DNS

October 1, 2020

Problem

GitLab Pages domain verification code

The steps mentioned in the GitLab documentation to verify the ownership of a subdomain don’t work if your domain’s DNS provider is Namecheap.

What doesn’t work:
Adding a CNAME record for the subdomain that points to namespace.gitlab.io (where namespace is your GitLab username)
and defining a TXT record with key _gitlab-pages-verification-code.subdomain.domain.tld for it

What works:
Definining an A record for the subdomain and a TXT record for it where the key is the subdomain name.

Steps

Here are steps needed to setup GitLab pages with a custom subdomain for Namecheap DNS:

  1. Login to Namecheap and go Account -> Domain List

  2. Click Manage button for the desired domain

  3. Select Advanced DNS tab

  4. Click ADD NEW RECORD red plus button

  5. Then add the following two DNS records for the subdomain: 5a. Create A record Host: subdomain Value: 35.185.44.232 (this is the IP address used by gitlab.io)

    5b. Create TXT record Host: subdomain Value: gitlab-pages-verification-code=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    Make sure to change the value of the verification code xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx with what GitLab generated for you.

The same steps can be followed for a custom domain, just replace the subdomain with the domain name.

Conclusion

Documentation can sometimes be wrong, outdated or not taking into consideration all possible cases.

You have to use critical thinking and find a solution in spite of what the docs says.