This is about configuring both an apex domain and www subdomain for GitHub Pages. I migrated this site to Jekyll and GitHub Pages previously.

The setup I want:

  • example.com is the canonical domain in GitHub Pages
  • www.example.com forwards to example.com
  • HTTPS works for both

The steps:

  1. Configure GitHub Pages in the repository settings.
  2. Set the custom domain as the apex domain, e.g. example.com.
  3. In the DNS provider, add a CNAME record for www -> <username>.github.io. Yes, just the user or organization domain. Do not include the repository name.
  4. For the apex domain, add either ALIAS/ANAME for example.com -> <username>.github.io, or use GitHub Pages A records if your DNS provider does not support ALIAS/ANAME.
  5. Set a low TTL while testing.
  6. Verify curl -I https://example.com returns content correctly.
  7. Verify curl https://example.com shows a redirect
  8. For www, verify curl -I https://www.example.com points back to https://example.com.
  9. Enable “Enforce HTTPS” in GitHub Pages once GitHub has issued the certificate.
  10. Set a higher TTL.

GitHub’s current docs also recommend verifying the custom domain before adding DNS entries. That prevents someone else from attaching one of your domains or subdomains to their repository while DNS is already pointed at GitHub Pages.

Useful checks:

dig example.com +noall +answer -t A
dig www.example.com +noall +answer
curl -I https://example.com
curl -I https://www.example.com