If you have already published your website with GitHub Pages, the next step is often using your own domain name.
Instead of using a default GitHub URL like:
yourusername.github.io- or
yourusername.github.io/project-name
you can connect a custom domain such as:
yourdomain.comwww.yourdomain.comblog.yourdomain.com
This makes your website look more professional and easier to remember.
In this guide, you will learn how to connect a custom domain to GitHub Pages in a simple step-by-step way.
Quick Summary
Here is the short version:
- GitHub Pages supports custom domains
- You can use:
- an apex/root domain like
yourdomain.com- or a subdomain like
www.yourdomain.com- First, add the custom domain in GitHub Pages settings
- Then update the correct DNS records with your domain provider
- For subdomains, you usually use a CNAME record
- For root domains, you usually use:
- A records
- or ALIAS / ANAME (if supported)
- DNS changes can take up to 24 hours
- You can enable HTTPS after setup
What You Need Before You Start
Before you begin, make sure:
- your website is already live on GitHub Pages
- you own a domain from a provider like:
- GoDaddy
- Namecheap
- Cloudflare
- Hostinger
- Google Domains alternatives
- you can access your DNS settings
- you have admin access to the GitHub repository
If your site is not live yet, publish it on GitHub Pages first.
Step 1: Open Your GitHub Pages Settings
Go to your GitHub repository.
Then:
- click Settings
- open Pages from the sidebar
- look for the Custom domain section
This is where you tell GitHub which domain you want to use.
Step 2: Enter Your Custom Domain in GitHub
In the Custom domain box, enter the domain you want to connect.
Examples:
yourdomain.comwww.yourdomain.comblog.yourdomain.com
Then click Save.
Important:
GitHub recommends adding the custom domain in GitHub before changing your DNS settings. This helps reduce the risk of domain takeover issues.
Good to know:
- If you publish from a branch, GitHub usually creates a CNAME file in the source branch automatically
- If you publish using a custom GitHub Actions workflow, GitHub does not create a CNAME file, and an existing CNAME file is not required
Step 3: Choose Your Domain Type
Before editing DNS, you need to know which type of domain you are connecting.
There are two common options:
1. Apex / Root Domain
This is the main domain without www.
Example:
yourdomain.com
2. Subdomain
This is a domain with a prefix.
Examples:
www.yourdomain.comblog.yourdomain.com
The DNS setup is different for each one.
Step 4: Connect a Subdomain (Like www.yourdomain.com)
If you want to use:
www.yourdomain.com
this is the easier option.
What to do:
Go to your domain provider’s DNS settings.
Create a CNAME record.
Example setup:
- Type:
CNAME - Host / Name:
www - Value / Target:
yourusername.github.io
Important:
The CNAME should point to:
yourusername.github.io- or
organizationname.github.io
Do not include the repository name in the target. GitHub specifically says the CNAME should point to the default GitHub Pages domain only.
Step 5: Connect a Root Domain (Like yourdomain.com)
If you want to use the main domain without www:
yourdomain.com
you usually need to create A records.
Add these 4 GitHub Pages A records:
185.199.108.153185.199.109.153185.199.110.153185.199.111.153
Example setup:
- Type:
A - Host / Name:
@ - Value:
185.199.108.153
Repeat that for all 4 IP addresses.
Optional:
If your DNS provider supports it, you can also use:
- ALIAS
- ANAME
These can point your root domain to:
yourusername.github.io
GitHub says an apex domain can use ALIAS, ANAME, or A records.
Step 6: (Optional) Add the www Version Too
Even if you use the root domain as your main domain, it is smart to also set up the www version.
Example:
- main domain =
yourdomain.com - also add =
www.yourdomain.com
Why?
GitHub can automatically redirect between the root domain and the www version depending on which one you set as the custom domain.
Recommended setup:
- Root domain → A records
www→ CNAME toyourusername.github.io
This gives a cleaner and safer setup.
Step 7: Wait for DNS Changes
After saving your DNS records:
- the changes may happen quickly
- or they may take time
GitHub notes that DNS propagation can take up to 24 hours.
So if your domain does not work right away, do not panic.
This is normal.
Step 8: Enable HTTPS
After the domain starts working, go back to:
- GitHub repository
- Settings
- Pages
Look for:
- Enforce HTTPS
Turn it on when the option becomes available.
Important:
GitHub notes that this option may take up to 24 hours to appear after the domain is configured.
Using HTTPS is strongly recommended because it makes your website more secure and trusted.
Should You Verify the Domain? (Recommended)
Yes — this is a very good idea.
GitHub recommends verifying your custom domain to improve security and reduce the risk of domain takeover attacks.
How domain verification works:
You add a TXT record in your DNS settings.
GitHub gives you the exact value in your profile Pages settings (not only the repository settings).
Why this matters:
If your domain is verified:
- other GitHub users cannot easily claim it for their own Pages site
- your setup is more secure
- your domain stays protected if something changes later
Important DNS Warning
Do not use wildcard DNS records like:
*.yourdomain.com
GitHub strongly warns against wildcard DNS records for GitHub Pages because they can create security risks and make domain takeover easier in some cases.
For most users, it is better to set only the exact records you need.
Common Beginner Mistakes to Avoid
Here are the most common mistakes:
1. Pointing CNAME to the wrong URL
For subdomains, point it to:
yourusername.github.io
Not:
yourusername.github.io/repository-name
2. Adding DNS first before GitHub
It is safer to add the custom domain in GitHub first.
3. Forgetting the 4 A records
For root domains, you need all 4 GitHub A records if you use the A record method.
4. Expecting instant results
DNS changes can take time.
5. Skipping HTTPS
Always enable HTTPS once GitHub allows it.
6. Not verifying the domain
Optional, but highly recommended for better security.
Simple Example Setups
If you want www.yourdomain.com
Use:
- CNAME
- Host:
www - Value:
yourusername.github.io
If you want yourdomain.com
Use:
- A records
- Host:
@ - Values:
185.199.108.153185.199.109.153185.199.110.153185.199.111.153
Best combined setup
If possible, use:
- root domain with A records
wwwwith CNAME
This is usually the cleanest setup.
Final Thoughts
Connecting a custom domain to GitHub Pages is not hard once you know the right order.
The simple process is:
- publish your site on GitHub Pages
- add the custom domain in GitHub
- update the correct DNS records
- wait for propagation
- enable HTTPS
- verify the domain for better security
If you are using a beginner-friendly static website, GitHub Pages + a custom domain is a very good setup.
It looks more professional, builds trust, and gives your site a cleaner URL than the default GitHub address.
FAQ
Can I use a custom domain with GitHub Pages?
Yes. GitHub Pages supports both root domains and subdomains.
Should I use www or the root domain?
Both work. For beginners, www is often easier because it uses a simple CNAME record.
What DNS record do I use for www on GitHub Pages?
Use a CNAME record pointing to:
yourusername.github.io
What DNS records do I use for the root domain?
Use either:
- A records (the 4 GitHub IPs)
- or ALIAS / ANAME if your provider supports it
How long does GitHub Pages custom domain setup take?
DNS changes can take up to 24 hours.
Does GitHub Pages create the CNAME file automatically?
If you publish from a branch, GitHub usually creates it after you save the custom domain. If you publish with a custom GitHub Actions workflow, it does not