Assigning a Google Domain to GitLab Pages

Before I jump into the nitty gritty of how to add a domain registered with Google Domains to a GitLab Pages site, I want to share a little backstory. If you're not interested in reading the human side of how and why I learned about custom domains with GitLab Pages, please skip ahead to the GitLab Pages section.

Backstory

A few years ago, I arrived home to my eight-year-old son excitedly telling me that he found a book at the library about HTML and built a website. This happened as a complete surprise and without any prodding from his software developer dad. After seeing the site, the dialog went something like this.

I told him, "that's great! Want me to put it on a server for you?"

"What's that!?" he asked.

"On a server, anyone can come see your site," I explained.

"Yeah!"

At the time, I was using a web host that required me to upload files via FTP. This proved to be a bottleneck in my son's workflow. Every time he had an update, he would bug me to upload it to the server.

Finally, I got wise and got out of his way. I put his code in a GitLab repository, and set up a GitLab Pages site. Then, I showed him the command line--which he tought was exceedingly cool--and taught him a few simple Git commands. And, voila! My son could publish changes as often as he wanted, without waiting for his old man.

This process continues to work well for both of us. But recently, I wanted him to feel a little more ownership of his site. You see, all of the sites he built were being served off of my generic GitLab domain https://stmcallister.gitlab.io/webkid/. So, rather than looking like he was piggybacking on my site, I wanted to get my son his own domain.

We went over to Google Domains and searched long and hard to find the name he wanted and arrived at http://ajmcweb.com. It's short. It's easy to spell. And, most importantly, he liked it!

Now, I needed to figure out how to assign the domain to the site. That's where the instruction piece of this article begins.

GitLab Pages

In the GitLab repository for the Pages site, go to Settings -> Pages. On the Settings page click the green New Domain button in the upper right corner.

On the New Pages Domain page enter the domain you want to use for your GitLab pages site. There are also options for entering certificates and private keys. Since the site we're simply static and not working with any kind of information, we did not set either of these values. When ready, click Create New Domain.

On the Pages Domain page you'll see a form entry for DNS that shows the CNAME entry of your new domain pointing to your GitLab Pages domain. Just below the DNS field is Verification status. Copy the value for Verification status, you'll need to add this to your Google Domain account to verify ownership of the domain you want to use.

Google Domains

In Google Domains, select your domain, go to the DNS section, and scroll down to Custom resource records. You will add two resource records to point your Google domain to your GitLab pages site.

First, take the value copied from the GitLab Verification status and create a resource record of type TXT. Paste the GitLab verification code in the Text field. The default value for TTL is set to 1H, but if you want to see changes occur more quickly, change it to 1m. Then, click Add.

TTL stands for Time to Live, and it stands for how long a copy of the record stays in cache before being discarded. That means if you leave the TTL set to 1m, then that resource is getting looked up every minute. So, after changing the value to 1m to see the DNS change populate, it would be a good idea to change it back to the 1H, or even 1D, value to reduce the numbers of look ups.

The next resource record to add is a DNS A record, which gives your domain an IP address for GitLab pages. As of this writing, that value is 35.185.44.232. You may also want to check the DNS A record documentation on GitLab Pages to make sure this value is still current.

With those two records set in Google Domains, go back to the Pages Domain page on GitLab and click the reload circle arrow to check if the domain now verifies. The unverified message should turn green and change to Verified. And, for a final test, point your browser to your new domain, and you should see your GitLab Pages site.

Now, my son is happy that his site has a custom domain. And--hopefully--you're happy that you found all this information in one article. You're welcome. ;)