How to Hook Up a Custom Domain to Your GitHub Repository

Darrin Mack profile image, in front of building


GitHub Checklist graphic

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.

Step 1: Activate GitHub Pages

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{username}/{repo}/settings/pages). Tell it to deploy from a branch and choose the branch (usually main).

Build and deployment screen in GitHub

Step 2: Buy A Domain

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.

Step 3: Link Your Domain on GitHub

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

Screen in GitHub to enter domain name

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.

Step 4: Edit DNS Records

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.

Screen to edit DNS records

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


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} - this way, GitHub knows where to look.

Screen to edit DNS records

Step 5: Back to GitHub, for SSL

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.

SSL confirmation screen in GitHub

That’s it!

Not too hard, was it?