Hellebusch.io

Setting Up a Custom Domain for GitHub Pages

2 min read

I’ve done this enough times it warrants a quick post to walk you through setting up a custom domain for your GitHub Pages site.

Prerequisites

  1. A GitHub repository with GitHub Pages enabled and published.
  2. A domain name purchased from a domain registrar (e.g., Namecheap, Google Domains, GoDaddy).
  3. Access to your domain registrar’s DNS settings.

Steps to Configure the Custom Domain

1. Update Your Domain’s DNS Settings

  1. Log in to your domain registrar and find the DNS management settings.

  2. Add the following DNS records:

    • A Records for the root domain (e.g., example.com):

      Type: A
Host: @
Value: 185.199.108.153
Value: 185.199.109.153
Value: 185.199.110.153
Value: 185.199.111.153
TTL: Default or Automatic

    • CNAME Record for the www subdomain:

      Type: CNAME
Host: www
Value: <username>.github.io
TTL: Default or Automatic

    Note: Replace <username> with your GitHub username.

2. Validate DNS Configuration

After updating the DNS records, use the dig command to validate the setup.

Validate the Root Domain (example.com)

Run the following command in your terminal:

dig example.com

Expected Output: Look for the A records in the ANSWER SECTION. It should return the four GitHub Pages IP addresses:

;; ANSWER SECTION:
example.com.        3600    IN    A    185.199.108.153
example.com.        3600    IN    A    185.199.109.153
example.com.        3600    IN    A    185.199.110.153
example.com.        3600    IN    A    185.199.111.153

Validate the www Subdomain (www.example.com)

Run the following command:

dig www.example.com

Expected Output Look for the CNAME record in the ANSWER SECTION. It should point to <username>.github.io:

;; ANSWER SECTION:
www.example.com.    3600    IN    CNAME    username.github.io.
username.github.io. 3600    IN    A        185.199.108.153
username.github.io. 3600    IN    A        185.199.109.153
username.github.io. 3600    IN    A        185.199.110.153
username.github.io. 3600    IN    A        185.199.111.153

Check Propagation

You can also use a tool like DNS Checker to confirm that your records have propagated globally.

3. Add Your Custom Domain in GitHub Pages

  1. In your GitHub repository:

    • Go to Settings → Pages.
    • Under Custom Domain, enter your domain name (e.g., example.com, notice no www).
    • Save the changes.

  2. Create a CNAME file in your repository containing the custom domain name (eg: example.com)

5. Verify and Enforce HTTPS

  1. Once your DNS changes propagate (may take up to 24 hours), return to Settings → Pages in your GitHub repository.
  2. Ensure Enforce HTTPS is enabled for secure access to your site.

Important Caveat: One CNAME per Domain

GitHub Pages only allows one repository to serve a custom domain or subdomain. If you set up multiple repositories with the same custom domain in their CNAME file, this will cause conflicts.