How to Add a Custom Domain to Your GitHub Pages Site

Apr 17, 2026

I just deployed my portfolio site to GitHub Pages, but the default username.github.io/repository-name URL looked unprofessional. I wanted to use mysite.com instead. When I tried to configure it, I got stuck on DNS settings for hours. Here’s what I learned.

The Core Issue

GitHub Pages uses a subdomain format by default: USERNAME.github.io/REPOSITORY-NAME. While functional, it doesn’t look polished. The solution is configuring a custom domain, but this requires two separate steps: DNS setup with your domain provider, and domain verification within GitHub.

DNS Configuration: Apex vs Subdomain

Before touching GitHub, you need to configure DNS records at your domain provider. The type of record depends on whether you’re using an apex domain (example.com) or subdomain (www.example.com, sub.example.com).

| Domain Type    | Record Type | Target Value                     |
|----------------|-------------|----------------------------------|
| example.com    | A records   | 185.199.108.153                  |
| example.com    | A records   | 185.199.109.153                  |
| example.com    | A records   | 185.199.110.153                  |
| example.com    | A records   | 185.199.111.153                  |
| sub.example.com| CNAME       | username.github.io              |
| www.example.com| CNAME       | username.github.io              |

Notice that apex domains require four A records pointing to GitHub Pages’ IP addresses, while subdomains use a single CNAME record pointing to your GitHub Pages URL.

I made the mistake here: I initially tried CNAME for my apex domain and got errors. GitHub rejects CNAME at the root domain level because DNS RFC standards don’t allow it.

Domain Verification Step

Before adding the domain in GitHub, you must verify ownership. This happens at the organization or profile level, not at the repository level.

Go to your organization settings or your profile settings
Navigate to Pages
Click “Add a domain”
Enter your domain
GitHub provides TXT records to add to your DNS configuration
Add these TXT records at your domain provider
Wait for DNS propagation (can take up to 48 hours, usually 5-30 minutes)

I skipped this step initially and got a “Domain not verified” error when trying to add the domain at the repository level. The verification must happen first.

GitHub Pages Configuration

Once DNS is configured and verified, configure GitHub:

1. Go to repository Settings
2. Click Pages in left sidebar
3. Find "Custom domain" section
4. Enter your domain (example.com or sub.example.com)
5. Click Save
6. Wait for green checkmark (DNS validation)
7. Check "Enforce HTTPS" (appears after validation)
8. Wait for SSL certificate provisioning (1-5 minutes)

The green checkmark is critical—it means GitHub successfully validated your DNS configuration. Without it, the “Enforce HTTPS” checkbox won’t appear.

DNS Propagation Reality

DNS changes don’t happen instantly. Here’s what I experienced:

My first attempt: I saved DNS records and immediately checked GitHub. Result: “DNS configuration not valid”
After 10 minutes: Still no change
After 30 minutes: Green checkmark appeared
Final step: HTTPS enabled automatically

Propagation time varies. Sometimes it takes 5 minutes, sometimes hours. The green checkmark is your signal to proceed.

Why HTTPS Matters

The “Enforce HTTPS” checkbox provides a free SSL certificate. Without it:

Browsers show “Not Secure” warnings
Visitors hesitate to trust your site
SEO rankings are affected
Mixed content errors break functionality

After enabling HTTPS, GitHub provisions a certificate automatically. Wait for the padlock icon in your browser to confirm it’s working.

Common Mistakes I Made

Used wrong record type: Tried CNAME for apex domain instead of A records
Skipped domain verification: Added domain to repo before verifying at org/profile level
Expected instant validation: DNS propagation takes time
Forgot about both www and root: If using example.com, consider also adding www.example.com with CNAME for better user experience

GitHub Pages uses Let’s Encrypt for SSL certificates. The certificates are automatically renewed before expiration. If you see SSL errors after the initial setup, check if DNS records were modified or if domain verification expired.

For security, GitHub checks DNS configuration periodically. If records change, your site might stop working. Always keep DNS records unchanged after initial configuration.

Custom domains improve brand perception and make sites more shareable. They also enable HTTPS by default when properly configured, which is essential for modern web standards.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Managing a custom domain for your GitHub Pages site
👨‍💻 Configuring an apex domain for your GitHub Pages site
👨‍💻 Troubleshooting custom domains

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!