GITLAB, PAGES, SUBDOMAIN, TUTORIAL, NAMECHEAP

How to setup gitlab pages domain and subdomain step by step

• Backstory
• Benefits
• Before we start
  • Prerequisites
  • Keywords replacement
• In your Gitlab Pages settings
• In your advanced DNS settings
  • Step 1 : add a A record
  • Step 2 : add a CNAME record
  • Step 3 : add a TXT record
  • Step 4 : refresh your Verification status

Backstory

Recently I’ve been struggling with Gitlab Pages custom domains. I followed the documentation meticulously, and it did not work. I kept receiving the following errors no matter how hard I tried :

If you are here, you probably had the same issue !
So what’s the matter ? It seems that gitlab documentation is actually wrong.

After many tests and failures by myself, I finally found out the always-working solution thanks to a namecheap article.

Benefits

Gitlab Pages is a free hosting solution for a static app, but it requires some technical skills ad the building process has to be managed by yourself. Here are few advantages :

1. It can host a private repo unlike Github pages
2. A config file is useable in multiple repos
3. There are many available templates that are ready to start with

If you want to have a whole comparison between Github pages and Gitlab pages, here is a more detailed article .

Before we start

Prerequisites

Make sure that you have :

• Deployed your Gitlab Pages (check this out if you ever want to deploy a react app)
• A domain name registered

In this specific example, I’m going to use namecheap as registar.

Keywords replacement

The name of my subdomain is jsonvizz and my original app aaa will be hosted at jsonvizz.jadynekena.com. I hightly recommand you to name your subdomain as same as your repo name, in order to not be confused. In summary :

• jsonvizz : replace it with yoursubdomain
• jadynekena.com : replace it with yourdomain.com
• jadynekena.gitlab.io. : replace it with yourusername.gitlab.io.
• yourverificationcodefromgitlab : replace it with your verification code in your gitlab pages settings

Let’s dive right in !

In your Gitlab Pages settings

Go to Settings > Pages > New domain, then write down your subdomain URL in the Domain field. In my case, I wrote down jsonvizz.jadynekena.com. Now on Create New Domain.

You will now have the following screen :

⚠️ DO NOT FOLLOW GITLAB INSTRUCTIONS UP THERE !⚠️
As stated before, those instructions are wrong. The only thing you will need later on is the gitlab-pages-verification-code=... part in Verification status.
Now let’s open another one with your advanced DNS settings.

In your advanced DNS settings

Step 1 : add a A record

In your DNS advanced settings, add a A record as follows:

Type: A
Host: @
IP: 35.185.44.232

The IP address here is pointing to the Gitlab Pages server.

Step 2 : add a CNAME record

Domain case

There is no need to add a CNAME record in domain case.

Subdomain case

Type: CNAME
Host: jsonvizz
Value: jadynekena.gitlab.io.

Do not forget the . at the end of the Value field, it is an important detail.

Please kindly refer to the keywords replacement if you have any doubt.

Step 3 : add a TXT record

From your Gitlab Pages settings , you will need the gitlab-pages-verification-code value.

Domain case

Type: TXT
Host: _gitlab-pages-verification-code
Value: gitlab-pages-verification-code=yourverificationcodefromgitlab

Subdomain case

Type: TXT
Host: _gitlab-pages-verification-code.jsonvizz
Value: gitlab-pages-verification-code=yourverificationcodefromgitlab

Please kindly refer to the keywords replacement if you have any doubt.

Step 4 : refresh your Verification status

Go back to your Gitlab Pages settings, and click on the Retry verification button. You should now have the success message as follows :

Now go to your website is available at yourdomain.com / subdomain.yourdomain.com.

If this article ever helped you, please let me know down below.
Happy hacking !