How to Add a Custom Domain to GitHub Pages?

GitHub Pages is a fantastic way to host static sites for free. By default, GitHub Pages provides you with a subdomain (username.github.io), but for a more professional look, you might want to use a custom domain. Adding a custom domain to your GitHub Pages site can make it easier for users to find and remember your website.

In this blog, we’ll walk through how to set up a custom domain with GitHub Pages, including the steps to configure your DNS settings and verify the domain setup.

---

Prerequisites

1. GitHub Pages Site: Make sure you have a GitHub Pages site up and running. If you don’t, create one by following GitHub’s instructions.
2. Registered Domain: You’ll need a custom domain name registered through a domain provider like GoDaddy, Namecheap, or Google Domains.

---

Step 1: Verify Your GitHub Pages Site is Live

Before adding a custom domain, ensure that your GitHub Pages site is accessible at the default GitHub URL (e.g., https://username.github.io/repository-name/). This ensures your project is ready to receive traffic from your custom domain.

1. Go to Settings in your GitHub repository.
2. Scroll to Pages under the “Code and automation” section.
3. Check that the site URL (under “GitHub Pages”) is live by clicking the link.

---

Step 2: Add Your Custom Domain in GitHub Settings

To configure GitHub Pages to use your custom domain, you need to update the repository settings.

1. In your repository, go to Settings and scroll down to the Pages section.
2. Under “Custom domain,” enter your custom domain (e.g., www.example.com).
3. Click Save.

GitHub will create a CNAME file in your repository’s root folder. This file contains your custom domain and tells GitHub Pages to direct your site to that domain.

---

Step 3: Configure Your Domain’s DNS Settings

To make your custom domain point to your GitHub Pages site, you’ll need to adjust the DNS settings through your domain registrar.

Setting Up A Records (For Apex Domains)

If you want users to access your site without “www” (e.g., example.com), you’ll need to configure A records in your domain’s DNS settings.

1. Go to your domain registrar’s DNS management page.
2. Add four A records, each pointing to GitHub’s IP addresses:

• 185.199.108.153
• 185.199.109.153
• 185.199.110.153
• 185.199.111.153

1. Save the changes.

Setting Up CNAME Record (For Subdomains)

If you want users to access your site with “www” (e.g., www.example.com), you need to add a CNAME record in your DNS settings.

1. Go to your domain registrar’s DNS management page.
2. Add a CNAME record with the following details:

• Name: www
• Value/Points to: username.github.io (replace username with your GitHub username).

1. Save the changes.

Note: DNS settings can take a few minutes to 48 hours to propagate, so your custom domain might not work immediately.

---

Step 4: Enforce HTTPS (Optional but Recommended)

GitHub Pages provides free HTTPS for custom domains, which encrypts data between your users and your website.

1. Go to your GitHub repository Settings.
2. Scroll down to the Pages section.
3. Under GitHub Pages, check the box next to Enforce HTTPS if it’s available.

If the checkbox is unavailable, wait until your DNS settings propagate fully. Once they do, GitHub should allow you to enable HTTPS.

---

Step 5: Verify the Setup

After you’ve set up your DNS records and configured GitHub Pages, it’s time to verify that your custom domain is working.

1. Open a browser and enter your custom domain (e.g., www.example.com).
2. Confirm that your GitHub Pages site loads on this domain.
3. If you enabled HTTPS, check that your domain starts with https:// rather than http://.

---

Troubleshooting Common Issues

1. Propagation Delay: DNS changes can take up to 48 hours to propagate globally. If your domain isn’t working immediately, give it some time.
2. Invalid CNAME Record: Ensure that your CNAME record points to your GitHub username, not your repository name.
3. HTTPS Enforcement Unavailable: If you can’t enable HTTPS, double-check your DNS settings and ensure they have fully propagated.

---

Summary of Steps

Here’s a quick recap of the process:

1. Set up and verify your GitHub Pages site.
2. Add your custom domain to your repository’s Pages settings.
3. Update your domain’s DNS settings with the correct A or CNAME records.
4. Enable HTTPS (optional).
5. Verify that your domain points to your GitHub Pages site.

---

Conclusion

Connecting a custom domain to your GitHub Pages site is a great way to make your project look more professional and memorable. By following these steps, you’ll ensure your GitHub Pages site is accessible through your unique custom domain. Once set up, your site will serve seamlessly, providing a clean and secure experience for visitors.