How to Set Up a Custom Domain on GitHub Pages

Alright, yourusername.github.io gets the job done. It’s free, simple, and hosted by GitHub, so you don’t have to worry about servers or monthly hosting.

But if you’re showing off a personal portfolio or a public project, connecting a custom domain makes a huge difference. Something like yourname.com doesn’t just look cleaner; it instantly feels like your brand. My blog at byalexdavid.com looks far more polished and memorable than a GitHub subdomain.

The best part is you don’t need expensive hosting or a complicated setup. GitHub Pages handles the hosting for free. All you need is a domain (usually $10 to 15 per year) and a few quick settings.

If you’re shopping for a domain, I recommend Hostinger. It’s affordable, the support replies quickly, and it’s what I use for my own domains.

In this guide, I’ll walk you through every step to connect a custom domain to GitHub Pages. Prefer to watch? There’s a short video right below that you can follow step by step. If you’re building locally first, you can also use live preview in VS Code to see changes instantly before you push to GitHub Pages.

Play YouTube video

Add Your Custom Domain to Your GitHub Repo

Now that you’ve got your domain name, it’s time to tell GitHub Pages about it.

1. Go to your GitHub repository that hosts your site.

2. Click on the Settings tab (usually at the top right).

3. Scroll down to the Pages section on the left sidebar.

4. Under Custom domain, enter your domain name (like yourname.com).

5. Click Save.

Once you do this, GitHub will automatically create a file named CNAME in your repository with your domain inside it. This file tells GitHub Pages to serve your site from your custom domain.

Heads up: If you ever want to remove or change your custom domain, just come back here and update or clear the field.

Set Up Your Domain’s DNS to Point to GitHub Pages

Now that you told GitHub about your custom domain, it’s time to connect your domain name to your site. This happens through DNS records basically, instructions your domain provider uses to know where to send visitors.

There are two main ways people use their domain with GitHub Pages:

• Apex domain (root domain): This is your plain domain, like yourname.com

• Subdomain: This is something like www.yourname.com or blog.yourname.com

For Your Apex Domain (like yourname.com)

If you want people to visit your site just by typing yourname.com, here’s what to do:

1. In your GitHub repo, go to Settings > Pages, and type your domain (yourname.com) under Custom domain, then save.

2. Next, head over to your domain provider (like Hostinger or Namecheap) and open your DNS settings.

3. You’ll need to add some records:

• If your provider supports it, add an ALIAS or ANAME record pointing to your GitHub Pages address (yourusername.github.io). These are special records that work for root domains.

• If your provider doesn’t support ALIAS or ANAME, add four A records with these IP addresses (one per record):

• If you want, you can also add AAAA records for IPv6 (the internet’s future), but it’s optional:

Tip: Because not everyone uses IPv6 yet, make sure you add those A records too.

For a Subdomain (like www.yourname.com)

If you want to use www.yourname.com instead of (or along with) your root domain:

• Add a CNAME record with:

  • Host/Name: www

  • Value: yourusername.github.io

This points your www address to GitHub.

A couple quick notes:

• If you want your site accessible both on yourname.com and www.yourname.com, set up both the apex domain records and the www CNAME record.

• DNS changes take some time to update anywhere from a few minutes up to 24 hours, but usually faster.

• Every domain provider looks different, so if you want, I can help you through your specific dashboard.

Wait for DNS to Update and Test Your Site

Once you've added the 4 A records from GitHub and set your custom domain in your repo settings, don’t panic if things don’t work right away this is where a lot of people mess up.

DNS changes take time to spread across the internet (called propagation). Sometimes it works in just a few minutes that’s usually what I see. But depending on your domain provider, it can take up to 24 hours.

If you see an error or the HTTPS checkbox isn’t showing yet, just be patient.
That doesn’t mean something’s broken. It just means DNS hasn’t fully updated yet. No need to keep deleting and re-adding your records or settings that just resets the clock and makes things take even longer.

You can check how your domain is propagating across the world here: https://dnschecker.org/  just type your domain and look for the A records.

Once DNS is fully updated, your site will load and the HTTPS option will appear automatically. Just wait it out and you’ll be good to go.

How to check if it’s working:

• Type your custom domain (like yourname.com) into a browser. If your GitHub Pages site loads, you’re all set!

• If it doesn’t show up yet, don’t worry  give it some more time and try again later.

Quick troubleshooting tips:

• Double check your DNS records for any typos or mistakes.

• Verify your custom domain is correctly set in your GitHub repo’s Pages settings.

• If you set up both root and www domains, try loading both in your browser.

Enable HTTPS and Fix Common Problems

Once your custom domain is working, the next important step is to secure your site with HTTPS. That little padlock in the browser bar means your site is encrypted and safer for visitors.

How to enable HTTPS on GitHub Pages:

1. Go to your repository’s Settings > Pages section.

2. Scroll to the Custom domain area.

3. Check the box that says Enforce HTTPS.

4. If you don’t see this option right away, wait a bit GitHub needs time to issue your SSL certificate. This usually happens within a few minutes to a couple of hours after your DNS is set up correctly.

Common issues and fixes:

• Site doesn’t load with HTTPS: Wait a little longer for the SSL certificate to be ready.

• Mixed content warnings: This happens if your site loads some resources (like images or scripts) over HTTP instead of HTTPS. Make sure all URLs in your site use https://.

• DNS misconfiguration errors: Double check your DNS records if you get errors about your domain not pointing correctly.

• 404 or site not found: Make sure your GitHub Pages branch and folder are set correctly, and your CNAME file exists if you’re using a custom domain.

Your Custom Domain is Live!

Setting up a custom domain on GitHub Pages might sound tricky at first, but once you break it down step by step, it’s really straightforward.

Recap:

• Buy a domain from your favorite provider (Hostinger, Namecheap, etc.)

• Add your custom domain in your GitHub repo settings

• Set up DNS records (A, CNAME, or ALIAS/ANAME) to point your domain to GitHub Pages

• Wait a few minutes for DNS changes to take effect

• Enable HTTPS for a secure connection

• Troubleshoot any issues if they pop up

Now you’ve got a professional looking website running on your own domain without paying for hosting!

If you want to dig into GitHub’s official guide, here it is:
👉 GitHub Docs – Managing a Custom Domain

And if you prefer watching, don’t forget to check out the video guide at the top.