Custom domains make your projects feel more legit, and they’re pretty easy to set up. This post will walk you through setting up a custom domain for github pages, but it assumes you have a few things already:
- github pages is set up for your project, e.g. you have a
{github_handle}.github.iosite you can view - You’ve purchased a domain
With those assumptions in place, let’s set up a custom domain! As an example, here’s a project I have hosted via github pages: countries.justinjoyce.dev1.
Step 1: Set up a CNAME record
Log into your domain name registrar’s site, and navigate to the DNS settings for your domain; in my case that’s dreamhost.com2. Now, set up a CNAME record like this:
In the screenshot above, Name means “the subdomain you want to use”, and Value is the end address you want that subdomain to end up at. Since this screenshot is from within the justinjoyce.dev settings, this CNAME record will point countries.justinjoyce.dev to my-github-handle.github.io.
Save your changes, and then go take a break. DNS changes take a while to propagate—they have to spread across the entire internet—and step 2 won’t work until your new CNAME record has propagated; this example took around 15 minutes to propagate.
Step 2: Use your new subdomain in your repo’s settings
Now go over to your respository in github. Click on settings, then on the left sidebar go to pages:
In Pages settings, enter your new desired domain under Custom Domain:
In the screenshot above there’s a green check mark and a line saying DNS check successful. If you did this soon after setting your CNAME record, the DNS check here might fail.
If your DNS check is failing, you probably didn’t do anything wrong. DNS changes take time to propagate. Check for typos, and then try again in a few minutes.
If your custom domain saves successfully, the final step is to enforce https. You don’t strictly have to enforce https, but it’s a good idea, and in the case of .dev domains it actually is required. Just below the custom domain settings is a checkbox for Enforce HTTPS.
The Enforce HTTPS block might say something like “waiting for a certificate”, indicating it’s not quite ready. There’s nothing for you to do, just check back in a few minutes and that checkbox should be ready to go. Once it’s checked, you’re all done!
Notes
- countries.justinjoyce.dev is a static web app I put together during the 2020 (2021) Olympics to get high-level overviews of the countries I was seeing compete. I also have a thing for flags, so it’s a quick way for me to look at them ↩︎
- They’re not paying me to say so, I’ve just had a good experience there. If anyone from dreamhost is reading this though feel free to send me a few bucks ???? ↩︎