Tutorial: Create a custom subdomain in Amazon Route 53 for a GitLab Pages website

When you create a GitLab Pages website, it has a default domain in the form of *.gitlab.io. You can register your own custom domain using a suitable domain registration service, then use that domain with your Pages website instead.

You might want to go a step further. What if you want multiple websites that use the same root domain, such as example.com, but are hosted separately?

For example, you have two websites: a cooking blog and an online store that sells your cookbooks and branded kitchen utensils. Because of the different nature of these sites, you use different website builders for each one. For your blog, you use a website builder that specializes in creating attractive posts. For your store, you use a website builder that has integrated payment options.

You want the same root domain for both sites, so it’s clear to users that they are still on your website. To do this, you can create a subdomain, which you do by adding a prefix to your root domain. For example, you can host your shop on example.com and create a subdomain called blog.example.com for your blog.

This tutorial takes you through the steps of creating a custom subdomain (blog.example.com) in Amazon Route 53 to use with your GitLab Pages website on GitLab.com.

Before you begin

You must have:

Add the custom domain and get the verification code in GitLab

  1. Sign in to GitLab at https://gitlab.com/users/sign_in.
  2. On the left sidebar, select Search or go to and find your project.
  3. Select Deploy > Pages.
  4. Copy the name of your default Pages domain name. It should look like *.gitlab.io. You’ll need this information when you set up the subdomain in Amazon Route 53.
  5. Select New domain.
  6. In Domain, enter the subdomain name. For example, blog.example.com.
  7. In Certificate, leave the Automatic certificate management using Let’s Encrypt toggle on.
  8. Select Create new domain.
  9. In Verification status, copy the verification information. You’ll need this information when you set up the subdomain in Amazon Route 53.
  10. Select Save changes.

Register a subdomain in Amazon Route 53

In this example, you have already registered a custom domain, www.example.com, in Amazon Route 53. Now, you’ll create a subdomain for your blog called blog.example.com.

To do this, create a CNAME and a TXT record in the hosted zone for the domain.

  1. Sign in to the AWS Management Console and open the Route 53 console at https://console.aws.amazon.com/route53/.
  2. In the navigation pane, select Hosted zones and select your custom domain.
  3. Select Create record.
  4. In Record name, enter the prefix for your subdomain. For example, blog.
  5. From the Record type dropdown list, select CNAME.
  6. In Value, enter the name of your default Pages domain name. It should have the format *.gitlab.io.
  7. Select Add another record.
  8. In Record name, enter the first part of the verification information that you copied earlier. It starts with _gitlab-pages-verification-code and ends with your custom subdomain. Enter everything up until the prefix only, for example, _gitlab-pages-verification-code.blog.
  9. From the Record type dropdown list, select TXT.
  10. For Value, enter the last part of the verification information that you copied earlier. It is found after TXT, starts with gitlab-pages-verification-code, and includes an alphanumeric code. Do not include the TXT.
  11. Select Create records.

Verify domain ownership in GitLab

  1. Return to GitLab.com.
  2. On the left sidebar, select Search or go to and find your project.
  3. Select Deploy > Pages.
  4. Next to the subdomain name, select Edit (a pencil icon).
  5. In Verification status, select Retry verification (a refresh icon).
  6. If the status is Verified, test your subdomain by selecting the Domain link.

You’re now using a subdomain for your GitLab Pages website!

It can take half an hour or longer for GitLab to get the Let’s Encrypt SSL certificate for your site. Until then, your website might display a Not Secure or Your connection is not private message. This is resolved when the certification process is complete.