A guide from TheWebSiteGuru.com
At TheWebSiteGuru.com we host simple sites on GitHub Pages because it costs you nothing. There's no monthly fee and no yearly hosting bill, which is why we use it to keep costs down for our customers and for all of our pro bono work. When we build you a website, we encourage you to host it this way.
You don't have to. If you'd rather use a paid hosting provider, you're welcome to pick any one you like. Expect to pay anywhere from under $100 a year to several hundred dollars a year, depending on the provider and plan. The only thing GitHub Pages asks of you is about half an hour to connect your domain, and this guide walks you through it.
This guide covers publishing your site with GitHub Pages and pointing a domain you bought at it. You'll need a GitHub account, a repository holding your site's files, and access to the DNS settings at the company where you bought your domain (GoDaddy, Namecheap, Cloudflare, Squarespace Domains, Porkbun, or similar).
After you make your changes, DNS can take anywhere from a few minutes to 24 hours to spread across the internet, so don't panic if things don't work right away.
Throughout this guide, example.com stands in for your domain and your-username stands in for your GitHub username. Replace both with your own.
If you've never used GitHub Pages before, this short tutorial from GitHub shows the whole process on screen. The steps below cover the same ground in writing, plus connecting your own domain.
main) and the folder (/ (root) or /docs), then click Save.After a minute or two, GitHub shows a message at the top of the Pages screen saying your site is live at https://your-username.github.io/repository-name/. Open that link to confirm the site works before you touch DNS. If it doesn't load here, it won't load on your domain either.
If your site is built with a GitHub Actions workflow instead, choose GitHub Actions as the source and follow your workflow's instructions. The domain steps below are the same either way.
Verifying the domain stops anyone else from claiming it for their own GitHub Pages site if your setup ever lapses. Do this once per domain.
example.com, and click Add domain.| Type | Name / Host | Value |
|---|---|---|
| TXT | _github-pages-challenge-your-username | a long random string GitHub gives you |
Leave the TXT record in place after verification. Deleting it removes the protection.
If the site lives under a GitHub organization rather than your personal account, do this from the organization's settings instead of your profile settings.
Log in to the company where you bought the domain and find the DNS settings. Different registrars call this screen different things: DNS, DNS Management, Manage DNS, Advanced DNS, or Zone Editor.
Most people want the site to work at both example.com and www.example.com. That takes two sets of records.
Create four A records, all with the host set to @:
| Type | Name / Host | Value |
|---|---|---|
| A | @ | 185.199.108.153 |
| A | @ | 185.199.109.153 |
| A | @ | 185.199.110.153 |
| A | @ | 185.199.111.153 |
You can also add these four AAAA records so visitors on IPv6 networks connect directly. They're optional but cost nothing:
| Type | Name / Host | Value |
|---|---|---|
| AAAA | @ | 2606:50c0:8000::153 |
| AAAA | @ | 2606:50c0:8001::153 |
| AAAA | @ | 2606:50c0:8002::153 |
| AAAA | @ | 2606:50c0:8003::153 |
Create one CNAME record:
| Type | Name / Host | Value |
|---|---|---|
| CNAME | www | your-username.github.io |
Point it at your GitHub username (or organization name) followed by .github.io. Don't include the repository name. That's the most common mistake in this whole process.
New domains often come with placeholder records that send visitors to a "parked" page from the registrar. Before or right after adding the records above, delete any of these:
@ that don't match the GitHub addresses abovewww that points somewhere elseLeave MX and TXT records alone. Those handle email and verification, and removing them can break your email.
If the registrar asks for a TTL, pick the lowest option offered (often 600 seconds or "1 hour") while you're setting things up. You can raise it later.
Some registrars fill in the domain for you, so in the Name/Host field you type www, not www.example.com. If you type the full name, you can end up with a record for www.example.com.example.com. Check what the registrar shows after you save.
If your domain uses Cloudflare for DNS, set each GitHub record to DNS only (grey cloud) instead of Proxied (orange cloud). GitHub has to see traffic come straight to it to issue your free HTTPS certificate. Once the certificate is issued you can experiment with turning the proxy back on, but DNS only is the simpler setup and works fine.
If your registrar doesn't allow a CNAME and only offers A records, that's unusual. Contact their support, or move the domain's DNS to a free provider like Cloudflare.
www.example.com and click Save.Use the www version here. GitHub will automatically redirect example.com to www.example.com as long as both sets of DNS records from Step 3 exist. If you'd rather your site's main address be the bare example.com, enter that instead and GitHub will redirect www the other way. Either works. Just pick one.
GitHub now runs a DNS check. You'll see a yellow "DNS check in progress" message, which turns into a green "DNS check successful" once your records have spread. If it shows an error, give it an hour and click Check again before troubleshooting.
When you publish from a branch, saving the custom domain adds a file named CNAME to the root of your publishing branch. Don't delete that file. If you delete it, your custom domain setting goes away with it. (Sites published with a GitHub Actions workflow don't use this file.)
Once the DNS check passes, GitHub requests a free security certificate for your domain. This usually takes a few minutes but can take up to 24 hours.
When it's ready, the Enforce HTTPS checkbox on the Pages settings screen becomes clickable. Tick it. From then on, anyone who visits http:// gets sent to the secure https:// version.
If the box stays greyed out with a message saying the certificate isn't ready, wait. If it's still grey after a day, remove the custom domain, click Save, add it again, and click Save once more. That starts a fresh certificate request.
Open each of these in a private or incognito browser window:
https://www.example.comhttps://example.comhttp://example.comAll three should land on your site with a padlock in the address bar.
You can also check the DNS records yourself. On Windows, open Command Prompt or PowerShell. On a Mac, open Terminal. Then run:
nslookup example.com
nslookup www.example.comThe first should list the four 185.199.x.153 addresses. The second should mention your-username.github.io.
Your browser shows the registrar's parked page or an old site. An old A record is still in place, or the registrar's forwarding feature is on. Delete it, then wait. Your own computer may also be holding onto the old answer, so try a phone on mobile data.
GitHub shows "Domain's DNS record could not be retrieved" or "improperly configured." Your records haven't spread yet, or one has a typo. Compare every value against Step 3 character by character.
You see a GitHub 404 page ("There isn't a GitHub Pages site here"). DNS is working, but GitHub doesn't know which repository owns the domain. Re-enter the custom domain in Step 4 and confirm the CNAME file exists in your publishing branch.
The browser warns that the connection isn't private. The HTTPS certificate hasn't been issued yet. Wait, and don't tick Enforce HTTPS until the box becomes available on its own. On Cloudflare, confirm the records are set to DNS only.
example.com works but www.example.com doesn't, or the reverse. One of the two sets of records from Step 3 is missing.
The site worked, then stopped after a change to the repository. Someone deleted the CNAME file or changed the Pages source branch. Check Settings, then Pages.
For anything not covered here, GitHub's official instructions are at docs.github.com. And if you get stuck, reach out to us at TheWebSiteGuru.com and we'll help you get your site live.