How to Hook Up a Custom Domain to Your GitHub Repository

When serving static websites, GitHub Pages is a terrific option. Your site is guaranteed to be fast and directly linked with your GitHub repository, so as code changes happen, they are reflected immediately.

But the purpose of this post isn’t to sell you on the idea of GitHub pages but rather to walk you through how to hook up a domain to your repo because GitHub’s own instructions can be confusing. We’re going to use our recently launched The Next F1 Race as a how-to guide.

Firstly, you’re going to need to set up GitHub Pages to do automatic deploys. Do this by visiting your repo and going to Settings > Pages. (The URL will be https://github.com/{username}/{repo}/settings/pages). Tell it to deploy from a branch and choose the branch (usually main).

Buy your domain using whatever registrar you prefer. In our example, we’re using Namecheap, which we think is a great option for domains. GoDaddy is a terrible option, please don’t ever buy a domain from GoDaddy.

Back on that GitHub Pages settings, you’ll see an entry for “Custom Domain” - enter in the appropriate domain there.

Doing this will create a file in your root directory called CNAME - you’ll never need to touch that file.

You’re now set up to receive the traffic, but now you need to tell the domain to send it.

There’s a number of ways to do this, but I’m gonna walk you thru our process: Go back to Namecheap and edit the domain. Keep your nameserver as “Namecheap Basic DNS” and make sure all your redirects are turned off.

Now switch over to the “Advanced DNS” tab and give it the four A Record entries, each with @ as the host.

1. 185.199.108.153
2. 185.199.109.153
3. 185.199.110.153
4. 185.199.111.153

You’ll also need to add a single CNAME entry (this is the part a lot of guides miss). Your CNAME should have the value of {username}.github.io - this way, GitHub knows where to look.

Now go back to the GitHub pages view, and you’ll see that it will be doing a DNS Check. This will sometimes take a bit because there has to be a confirmed connection between your registrar (in our case Namecheap) and GitHub Pages. Expect this could take somewhere between 2 minutes and 2 hours.

When the connection has been confirmed, GitHub will automatically generate an SSL certificate for you. This is always preferable, and every connection should be served in https mode if possible. So as soon as GitHub tells you that your cert has been generated, go ahead and check “Enforce HTTPS”, and every connection will serve from https.

That’s it!

Not too hard, was it?