How to Use a Custom Domain with GitHub Pages
So you’ve deployed your website using GitHub Pages, and you have a URL like your-username.github.io/my-cool-project. That’s great! But what if you want it to be accessible at a professional domain you own, like my-cool-project.com or www.my-cool-project.com?
This guide will walk you through the entire process of connecting a custom domain you’ve purchased to your GitHub Pages site.
Prerequisites
Before you begin, you need two things:
- A deployed GitHub Pages site: Your website should already be live at its
github.ioaddress. - A custom domain name: You must have already purchased a domain from a registrar like GoDaddy, Namecheap, Google Domains, etc.
Part 1: Configure Your Domain in GitHub
First, we need to tell GitHub which domain you’re going to use.
- Navigate to the GitHub repository for your website.
- Click the “Settings” tab.
- In the left sidebar, click on “Pages”.
- Scroll down to the “Custom domain” section.
- In the text box, type your custom domain name (e.g.,
www.yourdomain.comoryourdomain.com) and click “Save”.
After you save, GitHub will try to verify your domain. It will likely fail at first because you haven’t configured your domain’s DNS yet. GitHub will show you the records you need to add, but we’ll cover that in the next step.
Note: A file named
CNAMEwill automatically be created in your repository. This is normal and necessary—do not delete it!
Part 2: Configure Your DNS Records
This is the most important step. You need to go to your domain registrar’s website (where you bought the domain) and point it to GitHub’s servers.
- Log in to your domain registrar’s website (GoDaddy, Namecheap, etc.).
- Find the DNS management page for your domain. It’s often called “DNS Settings,” “Manage DNS,” or “Advanced DNS.”
- You will need to add DNS records. The type of records you add depends on the type of domain you are setting up.
Option A: Setting up a www Subdomain (e.g., www.yourdomain.com)
This is the most common and recommended method.
You need to create a CNAME record.
- Type:
CNAME - Host / Name:
www - Value / Points to:
your-username.github.io(replaceyour-usernamewith your actual GitHub username). - TTL: You can leave this at the default setting (usually “1 hour” or “Automatic”).
Delete any other A or AAAA records for the www host if they exist.
Option B: Setting up an Apex Domain (e.g., yourdomain.com)
An apex domain is the root domain without www. If you want your site to be accessible at yourdomain.com, you must use A records.
You need to create four separate A records pointing to GitHub’s IP addresses.
Create the first record:
- Type:
A - Host / Name:
@ - Value / Points to:
185.199.108.153 - TTL: Leave at default.
Now, create three more A records, each with the same Host (@) but with the following values:
185.199.109.153185.199.110.153185.199.111.153
When you are finished, you should have four A records all with the host @ pointing to those four different IP addresses. Delete any other A or AAAA records for the @ host if they exist.
Part 3: Wait for DNS Propagation
DNS changes are not instant. It can take anywhere from a few minutes to several hours (in rare cases, up to 48 hours) for your changes to take effect across the internet.
You can check the status by going back to your repository’s Settings > Pages page. GitHub will eventually show a green checkmark and the message “Your site is published at…” once the DNS is configured correctly.
You can also use a tool like whatsmydns.net to check if your domain is pointing to GitHub’s IP addresses.
Part 4: Enforce HTTPS
Once your site is live at your custom domain, a final crucial step is to secure it.
- Go back to your repository’s Settings > Pages page.
- Scroll down to the “Custom domain” section.
- You should now see a checkbox labeled “Enforce HTTPS.”
- Check this box.
This ensures that all traffic to your site is encrypted and secure, showing the padlock icon in the browser’s address bar. This option will only become available after your custom domain is successfully connected.
And that’s it! Your GitHub Pages site is now live on your professional custom domain.
@ars18 maybe reply how you used nginix reverse proxy
would be much appreciated!