How to setup gitlab pages domain and subdomain step by step


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 : Subdomain not verified in Gitlab Pages 1/2

Subdomain not verified in Gitlab Pages 2/2

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.

Goal of the article is to setup gitlab pages


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


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 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
  • : replace it with
  • : replace it with
  • 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 Now on Create New Domain. Create a new domain in Gitlab Pages

You will now have the following screen : Gitlab Pages domain settings

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: @

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
Host: jsonvizz

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 : Success verification status

Now go to your website is available at /

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