GitLab Pages with an AWS Route53 Custom Domain

Take a custom domain from AWS Route53 and route queries to a static site hosted on GitLab Pages.

Skip the talk, just show me how

You’ll need a good understanding of git to use this article. And there are plenty of ways to learn, but I can’t recommend one specific approach here. Do a search for it, find a mentor, go to meetups is my advice.

It’s also good to know what a subdomain is. Here’s my 2 second explaination:

Heres a beginner-friendly video for Standing up GitLab Pages with Hugo. Where you know you have a different preference than the speaker, you can go your own way.

Many Hugo themes use git submodules. I find them annoying, but it’s neccessary for the older themes in the collection. A lot of newer themes use a newer hugo mod tool. Shop around and find something that’s workable as far as styling, features, and maintainability.

Maybe you’re using Hugo, maybe it’s some other static site generator, maybe raw HTML, CSS & JS – I haven’t tried, but my guess is that there’s a way GitLab pages will allow that. Any of the above should work just fine with this.

This blog is just about the specific case of:

• “I’ve got my GitLab pages up and running on GitLab.”
• “My domain name is registered through Route53”
• “My pages site is ready to launch to AWS Route53”
• “I just need to get AWS to point to GitLab, and GitLab to serve AWS”

!! Vendor Lock-in Caveat !!

AWS Route53 will charge extra for each query where a domain name points outside of AWS’s data centers. So while GitLab Pages is free to host, AWS will charge you for using GitLab’s free service, or for any host you point your registered domains toward that’s not an AWS service.

Is that fair? Is the free market in a position to even have a say about it? I don’t know, and I’m not going to comment further in this article. There are a few options you can decide on now, however, if that above arrangement is not going to work for you.

1. Forget GitLab and host everything on AWS. Now you won’t have to worry about being charged for calls outside AWS. You will still be charged for useage of any compute or internal services AWS has. And there’s no guarantee it will net a smaller bill. But if you chose the AWS-all-in route, compute services such as EC2, EBS, Lightsail, or EKS may work for you. There is a plethora of options and configurations of options available. Even S3 storage can host simple HTML static sites. The benefit is everything is in AWS. The drawback is everything is in AWS. Vendor Lock-in. Hope they don’t raise prices.

2. Forget AWS Route53 and shop around for another domain registrar. The trouble here is if you’ve already purchased your domain name through AWS Route53, that may end up being a bit of a tricky operation. Maybe there’s a straightforward way to transfer registrars if you own the domain name, but that’s outside the scope of this blog. There’s also no guarantee the other registrars won’t also charge per-visit. But back in 2015 I know for a fact GoDaddy didn’t.

3. Just use GitLab.io, maybe for your needs its perfectly fine that you don’t use a custom domain name.

What about IaC?

If you’re worried about the changelog to your infrastructure and use infrastructure as code to maintain it, it may be easier just to keep a document of this somewhere. As a solo maintainer, that should be fine. Teams would need to agree and observe that proceedure though, and it’s really easy for someone to fail to update the docs while they make a hotfix. It’s not nearly as good as using terraform or a similar tool like it, but it also may be overkill to create and run a terraform just to point AWS to a GitLab Pages instance. If you’re feeling saucy and just want to learn terraform, I can see a use for it, then. We’ll be using the console in this blog. But using Terraform or the CLI or an app with an AWS SDK are all encouraged.

How to:

1. When you go to GitLab, select your repo. In the Settings > Pages there will be an “Add Custom Domain Name” or some such. Click it.

   

   

2. After you type in the domain you want to point at GitLab Pages, You’ll see these two records you need to put into AWS Route53. AWS’s Interface is different from this.

   

3. ALIAS in AWS can only be used internally with other AWS services in Route53. But for GitLab Pages, use CNAME, it works just as well.

4. AWS breaks these records into pieces in their console interface. (they may not be as broken-up using the CLI, but in the console, this is how it works.) The first part goes into the subdomain field. The operation goes into the dropdown. and the rest goes into that big-ol’ value box. Note: you’ll need to make sure you have permission to do this. Pelase make sure you have the right role to allow you to create Route53 records. There are plenty of articles around AWS permissioning best practices. Do a search for those, if you’re unaware of them.

   

   

   

   

5. You’ll also need a second TXT record with a super specific subdomain. It’s supplied in GitLab, and used to continually prove you own the domain name.

   

   

   

   Note: This TXT record needs to be a separate record from the CNAME in a separate subdomain. If any AWS subdomain has a CNAME on it, it cannot have any other records on it at all. That subdomain does nothing but point somewhere else.

6. So when you’re done, it should look like this in AWS Hosted Zones

   

7. The verification on GitLab should now work, and unless you have a very compelling reason not to, make it https. GitLab does an automated certificate generation process that happens behind the scenes and takes maybe 5 minutes to complete.

You should now see your new static site on your custom domain!