How to Set Up Apex Domain Redirect for GitHub Pages

The Problem: GitHub Pages and Apex Domains

GitHub Pages is one of the most popular free hosting solutions for static websites, documentation, and project pages. It works beautifully out of the box with a username.github.io URL, but most people want to use their own custom domain.

Here is where things get tricky. GitHub Pages custom domains rely on a CNAME record to route traffic from your domain to GitHub's servers. CNAME records work perfectly for subdomains like www.yourdomain.com, but there is a fundamental DNS limitation: you cannot place a CNAME record on an apex domain (also called a root, bare, or naked domain).

The reason is technical but important. The DNS specification (RFC 1034) states that a CNAME record cannot coexist with other records at the same name. Since the apex domain (yourdomain.com) must have SOA and NS records to function, placing a CNAME there would break DNS resolution entirely. This means you cannot simply point yourdomain.com at username.github.io using a CNAME.

So what happens when someone types yourdomain.com into their browser? Without proper configuration, they get an error. That is a terrible experience, especially since many visitors omit the www prefix.

GitHub's Solution vs. ApexToWWW

GitHub does offer its own approach to this problem. You can add A records pointing your apex domain directly to GitHub's IP addresses (185.199.108.153 through 185.199.111.153). This sends traffic for yourdomain.com straight to GitHub's servers, which then serve your site.

While this works, it comes with drawbacks:

• No CDN flexibility — Your apex domain traffic is locked to GitHub's infrastructure. If you later move your site to Netlify, Vercel, or another host, you have to reconfigure everything.
• Mixed configuration — You end up with A records for the apex and a CNAME for www, creating two different paths to your content.
• IPv6 limitations — GitHub's A records are IPv4 only. Modern best practice includes AAAA records for IPv6 connectivity.

A cleaner approach is to serve your site exclusively on www.yourdomain.com and set up a proper 301 redirect from the apex domain. This is where ApexToWWW comes in. Instead of pointing your apex domain at GitHub, you point it at ApexToWWW, which issues an instant 301 redirect to www.yourdomain.com. Your www subdomain then resolves to GitHub Pages (or any other host) via a standard CNAME.

This architecture is cleaner because it separates concerns: the apex redirect is handled by a dedicated service, and your actual hosting can be anywhere.

Step-by-Step: Setting Up GitHub Pages with a Custom Domain and Apex Redirect

Follow these five steps to get your GitHub Pages site running on a custom domain with a proper apex redirect.

Step 1: Add a CNAME File to Your Repository

In the root of your GitHub Pages repository (or the docs/ folder if that is your publishing source), create a file named CNAME with a single line containing your www subdomain:

www.yourdomain.com

Commit and push this file. GitHub will automatically detect it and begin serving your site on that domain once DNS is configured. You can also set this through the GitHub repository settings under Pages > Custom domain.

Step 2: Configure the WWW CNAME Record

Log in to your DNS provider (Cloudflare, Namecheap, GoDaddy, Route 53, or whichever you use) and add a CNAME record for the www subdomain:

Replace username with your actual GitHub username (or organization name). This tells DNS to route all www.yourdomain.com traffic to GitHub's servers.

Step 3: Set Up the Apex Redirect with ApexToWWW

Now for the apex domain. Instead of using GitHub's A records, add the following DNS records to redirect yourdomain.com to www.yourdomain.com via ApexToWWW:

That is it for DNS. The A record handles IPv4 traffic and the AAAA record handles IPv6. When a visitor goes to yourdomain.com, ApexToWWW responds with a 301 permanent redirect to www.yourdomain.com, which then loads your GitHub Pages site. The redirect preserves the full path and query string, so yourdomain.com/about?ref=nav becomes www.yourdomain.com/about?ref=nav.

ApexToWWW handles SSL automatically via Let's Encrypt, so both HTTP and HTTPS requests are redirected securely. No account or signup is required.

Step 4: Enable HTTPS in GitHub Pages Settings

Once DNS has propagated (usually 5 to 30 minutes), go to your repository's Settings > Pages section in GitHub. You should see your custom domain listed. Check the "Enforce HTTPS" box. GitHub will provision an SSL certificate for www.yourdomain.com through Let's Encrypt.

If the option is grayed out, wait a few more minutes for DNS propagation and certificate provisioning to complete. You can verify DNS resolution by running:

dig www.yourdomain.com CNAME
dig yourdomain.com A
dig yourdomain.com AAAA

Step 5: Verify Everything Works

Test all four URL variations to make sure they resolve correctly:

• http://yourdomain.com → redirects to https://www.yourdomain.com
• https://yourdomain.com → redirects to https://www.yourdomain.com
• http://www.yourdomain.com → redirects to https://www.yourdomain.com
• https://www.yourdomain.com → loads your site

You can test redirects from the command line with curl -I yourdomain.com to inspect the response headers. You should see a 301 Moved Permanently with a Location header pointing to your www URL.

This Pattern Works Beyond GitHub Pages

The approach described here is not specific to GitHub Pages. The same "www via CNAME, apex via redirect" pattern works with virtually any hosting platform that supports custom domains through CNAME records:

• Netlify — Point your www CNAME to your Netlify site URL and use ApexToWWW for the apex.
• Vercel — Set www as a CNAME to cname.vercel-dns.com and redirect the apex.
• Heroku — CNAME your www to your Heroku app's DNS target and redirect the apex.
• Firebase Hosting — Use a CNAME for www and let ApexToWWW handle the naked domain.
• Render, Fly.io, Railway — Same pattern applies wherever CNAME-based custom domains are used.

The beauty of this setup is portability. If you later migrate from GitHub Pages to Netlify, you only need to update the www CNAME record. The apex redirect through ApexToWWW stays exactly the same.

Summary

Setting up a GitHub Pages custom domain with an apex redirect takes about five minutes and requires just three DNS records: a CNAME for www pointing to GitHub, plus an A and AAAA record for the apex pointing to ApexToWWW. This gives you a clean, portable setup with automatic SSL on both the apex and www, full path preservation on redirects, and IPv6 support out of the box.