1. Buying a Domain

You need a domain name to point to your GitHub Pages site. Here are popular domain registrars.

2. Setting Up DNS Records

DNS (Domain Name System) tells the internet where to find your site. You need to add specific records pointing to GitHub's servers.

For the www Subdomain

Add a CNAME record that points www to your GitHub Pages URL:

# DNS Record
Type:  CNAME
Name:  www
Value: YOUR_USERNAME.github.io
TTL:   3600

For the Root Domain (Apex)

Add A records pointing to GitHub's IP addresses:

# DNS Records
Type:  A
Name:  @
Value: 185.199.108.153
TTL:   3600

Type:  A
Name:  @
Value: 185.199.109.153
TTL:   3600

Type:  A
Name:  @
Value: 185.199.110.153
TTL:   3600

Type:  A
Name:  @
Value: 185.199.111.153
TTL:   3600

Complete DNS Setup

3. Configuring GitHub Repository

After setting up DNS, tell GitHub about your custom domain.

Step-by-Step

1. Go to your repository on GitHub
2. Click Settings → Pages (in the left sidebar)
3. Under Building and deployment, find the Custom domain section
4. Enter your domain: yourdomain.com
5. Click Save
6. Wait for DNS check to complete (may take a few minutes)
7. Check Enforce HTTPS once the certificate is provisioned

4. Creating CNAME File

GitHub Pages requires a CNAME file in your repository root to know which domain to serve.

Manual Creation

# In your project's public/ or root directory
echo "yourdomain.com" > public/CNAME

# For Create React App
echo "yourdomain.com" > public/CNAME

# For Vite
echo "yourdomain.com" > public/CNAME

The CNAME File Content

# public/CNAME — just one line, no extra spaces or lines
yourdomain.com

5. Enforcing HTTPS

GitHub Pages provides free SSL certificates through Let's Encrypt. Once your domain is verified, you can enable HTTPS.

Enable HTTPS

1. Go to repository Settings → Pages
2. Under Custom domain, check Enforce HTTPS

Wait for Certificate

GitHub automatically provisions a Let's Encrypt SSL certificate. This usually takes 5-15 minutes but can take up to 24 hours.

# Verify SSL is working
curl -I https://yourdomain.com

# Should show:
# HTTP/2 200
# strict-transport-security: max-age=31536000
# x-content-type-options: nosniff

6. Setting Up Apex Domain

The apex domain (also called root domain or bare domain) is yourdomain.com without the www prefix.

The Challenge

GitHub Pages doesn't support ALIAS or ANAME records, which means you can't directly point a root domain to a CNAME. Instead, you must use A records.

Cloudflare Alternative (Recommended)

If you use Cloudflare, you can use their CNAME flattening feature:

# In Cloudflare DNS dashboard
Type:  CNAME
Name:  @
Value: username.github.io
Proxy: DNS only (gray cloud)

Traditional DNS (A Records)

# Point root domain to GitHub's IPs
Type:  A
Name:  @
Value: 185.199.108.153

Type:  A
Name:  @
Value: 185.199.109.153

Type:  A
Name:  @
Value: 185.199.110.153

Type:  A
Name:  @
Value: 185.199.111.153

7. Testing Your Domain

After configuring everything, verify that your domain works correctly.

DNS Propagation Check

# Using dig (Linux/Mac)
dig yourdomain.com +short
# Should show: 185.199.108.153 (or similar)

dig www.yourdomain.com +short
# Should show: username.github.io

# Using nslookup (Windows)
nslookup yourdomain.com
nslookup www.yourdomain.com

Online Tools

• dnschecker.org — Check DNS propagation worldwide
• whatsmydns.net — Visual DNS propagation map
• ssllabs.com/ssltest — Verify SSL certificate

Verify Site Loads

# Test HTTP response
curl -I http://yourdomain.com
# Should redirect to https://yourdomain.com

curl -I https://www.yourdomain.com
# Should return 200 OK

8. Best Practices

SEO Considerations

# Add a canonical link in your HTML head
<link rel="canonical" href="https://yourdomain.com" />

# Redirect non-www to www (or vice versa) in your index.html
# Add this meta tag for search engines
<meta http-equiv="refresh" content="0;url=https://yourdomain.com">

# Use consistent URLs in your sitemap
<url>
  <loc>https://yourdomain.com/</loc>
</url>

Redirect Setup

Choose ONE canonical version (either with or without www) and redirect the other.

# In your repository root, create a simple redirect
# For root → www redirect:

# Create separate HTML files for the non-canonical domain
# Or use Cloudflare Page Rules for automatic redirects

# Cloudflare Page Rule (free tier allows 3)
# URL: http://yourdomain.com/*
# Setting: Forwarding URL (301)
# Destination: https://www.yourdomain.com/$1

Performance Tips

• Enable Cloudflare proxy for caching and DDoS protection (optional)
• Use relative URLs in your React app to avoid mixed content issues
• Set proper Cache-Control headers for static assets
• Add a 404.html page that redirects back to your main site

Quick Reference: Full DNS Configuration

# Complete DNS setup for GitHub Pages with custom domain

# Root domain → GitHub (A records)
@  A     185.199.108.153
@  A     185.199.109.153
@  A     185.199.110.153
@  A     185.199.111.153

# www → GitHub (CNAME)
www  CNAME  username.github.io

# GitHub-side CNAME file
# File: public/CNAME
# Content: yourdomain.com

# GitHub Settings → Pages
# Custom domain: yourdomain.com
# Enforce HTTPS: ✅