Free step-by-step guide

Connect your own domain to GitHub Pages

Host a fast website for free on GitHub Pages, reachable at your own address like www.yourdomain.com, with HTTPS. This is the exact setup that runs musathegiant.com.

Last updated 1 October 2026

Before you start

  • A free GitHub account. Sign up at github.com.
  • A domain name from any registrar, such as Domains.co.za, Afrihost, Namecheap, GoDaddy or Cloudflare.
  • Access to your domain’s DNS settings, usually called “DNS management” or “Manage DNS” in your registrar’s dashboard.
  • About 30 minutes, plus waiting time while DNS updates.

Throughout this guide, replace USERNAME with your GitHub username and yourdomain.com with your real domain.

The 6 steps

  1. Publish your site with GitHub Pages

    Create a new repository and upload your website files, with your home page named index.html. Then open the repository’s Settings → Pages. Under Build and deployment, set Source to Deploy from a branch, choose main and / (root), and click Save.

    After a minute or two your site is live at https://USERNAME.github.io/REPOSITORY/. Open it to make sure it works before you continue.

  2. Verify your domain with GitHub

    This step proves you own the domain, so nobody else can ever publish a GitHub Pages site on it. Do it before you change any DNS records.

    Click your profile picture → Settings (your account settings, not the repository’s) → Pages → Add a domain. Type yourdomain.com and GitHub shows you a TXT record like this:

    TypeHost / NameValue
    TXT_github-pages-challenge-USERNAMEThe code GitHub shows you

    Add that record at your DNS provider, wait a few minutes, then click Verify. Keep this TXT record in place permanently.

  3. Add the custom domain to your repository

    Go back to the repository’s Settings → Pages. Under Custom domain, type www.yourdomain.com and click Save.

    When you publish from a branch, GitHub adds a file called CNAME to your repository holding your domain. Leave it there. If you publish with a GitHub Actions workflow instead, no CNAME file is needed.

  4. Create the DNS records

    At your DNS provider, delete any old “parking” A or CNAME records for @ and www, then add these:

    TypeHost / NamePoints to / ValuePurpose
    CNAMEwwwUSERNAME.github.ioYour main address
    A@185.199.108.153The bare domain, which GitHub redirects to www
    A@185.199.109.153
    A@185.199.110.153
    A@185.199.111.153

    All four A records at once:

    185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

    Optional, for IPv6: add four AAAA records for @:

    2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

    Tips. The CNAME value is only your username plus .github.io, without the repository name. Some providers call @ the “root” or leave the name blank. Don’t create a wildcard record like *.yourdomain.com. On Cloudflare, set these records to DNS only (grey cloud) until HTTPS is working.

  5. Check that DNS has updated

    DNS changes usually show up within minutes, but can take up to 24 hours. On Mac or Linux, run:

    dig www.yourdomain.com +nostats +nocomments +nocmd
dig yourdomain.com +noall +answer -t A

    The first should show a CNAME to USERNAME.github.io. The second should list the four 185.199.x.153 addresses. On Windows or your phone, an online tool such as a DNS checker website works too. Back in Settings → Pages, GitHub shows “DNS check successful” when it’s right.

  6. Turn on Enforce HTTPS

    Once DNS is correct, GitHub issues a free security certificate. This usually takes a few minutes to an hour. When the Enforce HTTPS box becomes available in Settings → Pages, tick it. Your site now loads securely at https://www.yourdomain.com, and visitors who type the bare domain are redirected automatically.

Troubleshooting

ProblemFix
“Domain’s DNS record could not be retrieved” or “improperly configured”Check the records in step 4 for typos, delete old parking records, and wait. DNS can take up to 24 hours.
Enforce HTTPS is greyed outWait up to an hour after DNS is correct. If it stays greyed out, remove the custom domain, save, then add it again. If you use CAA records, one must allow letsencrypt.org.
“Domain is already taken”Complete the verification in step 2. That claims the domain for your account.
Custom domain disappears after you upload filesYour upload deleted the CNAME file. Re-add the domain in Settings, or keep a file named CNAME (all capitals) containing only www.yourdomain.com.
Site shows a 404 pageMake sure your home page is named index.html and sits in the folder you chose in step 1.
Old version still showingClear your browser cache or open the site in a private window.

Common questions

How much does GitHub Pages hosting cost?

Hosting a public website on GitHub Pages is free. You only pay your registrar for the domain name itself, usually once a year.

Should I use www or the bare domain?

Use www.yourdomain.com as the main address and set up both. GitHub then redirects the bare domain (yourdomain.com) to www automatically, and www works better with DNS providers and CDNs.

How long does it take to go live?

Usually minutes to a few hours. DNS changes can take up to 24 hours to spread, and the HTTPS certificate can take up to an hour after DNS is correct.

Why is Enforce HTTPS greyed out?

GitHub has not issued the certificate yet. Check your DNS records are correct, wait up to an hour, and if it stays greyed out, remove the custom domain in Settings, save, then add it again.

Need a hand?

This guide follows GitHub’s official documentation on managing a custom domain and verifying your domain. If you get stuck, message me and tell me which step you’re on.

All contact options