Wiring a custom domain from Namecheap to GitHub Pages sounds straightforward until a stale DNS record breaks your build, or you get stuck waiting hours for an SSL certificate that won’t issue. Getting Namecheap BasicDNS configured properly with GitHub’s Anycast IPs, setting up clean redirects, and locking down Let’s Encrypt HTTPS only takes a few minutes if you do things in the right order.
Whether you’re shipping a docs site, a portfolio, or a static SPA, here is how to set up the DNS records cleanly so you don’t run into certificate timeouts or broken routing later.
The Apex vs Subdomain Strategy for GitHub Pages
Before changing any DNS records, decide what your canonical URL should be. GitHub Pages supports two setups: an apex domain (example.com) with a www fallback, or a standalone subdomain like docs.example.com.
If you want visitors to hit example.com and land on www.example.com (or the other way around), you need four Apex A records plus a single CNAME record. GitHub handles the redirect between apex and subdomain automatically based on whichever domain you save in your repo settings.
Here is how the routing works under the hood:
- Apex Domain (example.com): Resolves to GitHub’s Anycast IP addresses via four
Arecords. - WWW Subdomain (www.example.com): Points directly to your GitHub Pages host via a
CNAMErecord (likeusername.github.io). - Certificate Provisioning: GitHub requests a Let’s Encrypt cert covering both domains once DNS resolution clears.
If you previously configured custom nameservers on this domain, check how to create custom nameservers in Namecheap before rolling things back to default.
Configure Apex A Records in Namecheap BasicDNS
Log in to Namecheap, go to your Domain List, and click Manage next to your domain.
Make sure the Nameservers dropdown is set to Namecheap BasicDNS. If it is currently on Web Hosting DNS or Custom DNS, switch it back to BasicDNS and hit the green checkmark to save.
Head over to the Advanced DNS tab. Clear out any old default parking records, conflicting A records, or URL redirects attached to @ or www. Then add these four A records pointing to GitHub’s Anycast IP pool:
Type: A Record | Host: @ | Value: 185.199.108.153 | TTL: Automatic
Type: A Record | Host: @ | Value: 185.199.109.153 | TTL: Automatic
Type: A Record | Host: @ | Value: 185.199.110.153 | TTL: Automatic
Type: A Record | Host: @ | Value: 185.199.111.153 | TTL: AutomaticThese four IPs route incoming requests across GitHub’s global edge network. You can also add IPv6 AAAA records (2606:50c0:8000::153 through 2606:50c0:8003::153), but the standard A records will cover your traffic fine.
Set Up the CNAME Record for the WWW Subdomain
In the same Advanced DNS tab in Namecheap, create a CNAME record for your www host so traffic sent to www.yourdomain.com hits your repo properly.
Add a new record with these values:
Type: CNAME Record
Host: www
Target: yourusername.github.io.
TTL: AutomaticReplace yourusername with your actual GitHub username or organization name. Never point the CNAME to a specific repo path like username.github.io/repo—it must point directly to your root user domain.
If you are working on more complex subdomain setups, take a look at our guide on how to set up wildcard subdomains in Namecheap DNS or see how to point Namecheap domains to Vercel if you’re comparing static hosts.
Commit the CNAME File and Configure Repository Settings
Next, hop over to your repository on GitHub. You need to tell GitHub which custom domain belongs to this project.
Go to Settings > Pages. Under Custom domain, enter your primary domain (for example, www.example.com or example.com) and click Save.
GitHub will commit a CNAME file to the root of your publishing branch. If you use a build step (Vite, Astro, Hugo, Next.js static export), your deployment workflow will wipe this file on the next push unless you store a copy inside your static assets directory.
To stop your deployment pipeline from nuking the domain setting, add the CNAME file straight to your project’s public folder:
# For Vite / Astro / Next.js static exports, place CNAME in the public directory
echo "www.example.com" > public/CNAME git add public/CNAME
git commit -m "chore: add custom domain CNAME file"
git push origin mainFor more on how GitHub handles edge routing, check out the official GitHub Pages Custom Domain Documentation.
Verify DNS Propagation from the Command Line
Namecheap BasicDNS usually updates within 5 to 15 minutes, but your local resolver might still serve cached answers. Use dig to check what external DNS servers are seeing.
# Check the apex A records
dig +noall +answer example.com A # Check the www CNAME record
dig +noall +answer www.example.com CNAMEWhen you query the apex domain, you should see all four GitHub IP addresses listed in the answer section:
;; ANSWER SECTION:
example.com. 1798 IN A 185.199.108.153
example.com. 1798 IN A 185.199.109.153
example.com. 1798 IN A 185.199.110.153
example.com. 1798 IN A 185.199.111.153If you’re still seeing old hosting IPs, flush your local resolver cache or query an external public resolver directly with dig @1.1.1.1 example.com.
Enforce HTTPS and Let’s Encrypt Certificate Provisioning
Once GitHub’s DNS check turns green with “DNS check successful”, GitHub automatically triggers an SSL certificate request through Let’s Encrypt.
Go back to Settings > Pages and find the Enforce HTTPS checkbox. If it’s disabled with a note saying the certificate hasn’t been issued yet, wait about 10 to 15 minutes for the ACME challenge to complete.
Once it finishes, check the Enforce HTTPS box. You can verify your SSL handshake and redirect behavior with curl:
curl -Iv https://example.comYou should see a clean handshake with Let’s Encrypt Authority and an HTTP 200 (or a 301 redirect to your canonical domain).
Common Gotchas and How I Fixed Them
Here are the three issues I run into most often when debugging GitHub Pages DNS setups:
1. The Build Pipeline Wipes the CNAME File
If your domain disconnects after every Git push, your CI/CD pipeline (like GitHub Actions) is overriding the root with build output that lacks the CNAME file. Put the CNAME file inside your framework’s public/ or static/ directory so it copies into dist/ or build/ on every run.
2. Existing CAA Records Blocking Let’s Encrypt
If GitHub gets stuck on certificate generation, check your Namecheap DNS records for CAA rules. If you have an old CAA record that only allows DigiCert or Sectigo, Let’s Encrypt will be blocked. Add a CAA record allowing letsencrypt.org or remove the restrictive record.
3. Default Parking Page Conflicts
New Namecheap domains come with default parking page records (a Parking CNAME or URL Redirect). If you leave those in place when adding your GitHub A records, Namecheap returns conflicting answers and GitHub’s DNS validator will fail.
If you plan to run email on the same domain, make sure your MX records don’t interfere with your apex records. See our tutorial on how to route custom domain email to Google Workspace with Namecheap DNS.
Frequently Asked Questions
Can I use Cloudflare nameservers instead of Namecheap BasicDNS?
Yes. If you switch to Cloudflare nameservers, add the same four A records and CNAME there. Just make sure the records are set to DNS Only (grey cloud) during the initial GitHub SSL setup so the ACME challenge resolves without proxy interference.
How long does the GitHub Pages SSL certificate take to generate?
Usually 5 to 30 minutes after DNS finishes propagating. In rare cases where Let’s Encrypt hits rate limits or DNS resolution lags, it can take up to 24 hours. Leave Enforce HTTPS unchecked until the certificate status shows active.
Can I point multiple custom domains to a single GitHub Pages repo?
No, GitHub Pages only binds one custom domain per repository. If you have multiple domains, set your primary domain in GitHub and configure URL redirects in Namecheap for the rest.
Next Steps
Once your DNS propagates and HTTPS is enforced, your site is good to go. If you ever outgrow simple static hosting or need serverless edge functions, you can easily shift your domain over—check out how to configure Vercel custom DNS configurations when you’re ready to migrate.
