GitHub Pages is a popular way to host websites for free directly from your GitHub repository. By default, your site is accessible via a GitHub subdomain like username.github.io/repository, but you can give it a professional touch by connecting a custom domain (e.g., www.yourdomain.com).
In this blog, we’ll guide you through the process of adding a custom domain to your GitHub Pages site — whether you’re using a root domain (yourdomain.com) or a subdomain (blog.yourdomain.com).
Why Use a Custom Domain with GitHub Pages?
- Branding: Makes your site look professional and trustworthy.
- SEO Benefits: Helps improve your search engine ranking.
- Memorability: Easier for visitors to remember your URL.
- Flexibility: Full control over your domain and SSL certificates.
Prerequisites
Before you start, you need:
- A GitHub repository with GitHub Pages enabled.
- A custom domain purchased through a domain registrar (like GoDaddy, Namecheap, Google Domains, etc.).
- Access to your domain’s DNS management panel.
Step 1: Configure GitHub Pages
- Go to your GitHub repository.
- Navigate to Settings > Pages (or Code and automation > Pages in the new UI).
- Under Custom domain, enter your domain name (e.g.,
www.yourdomain.com). - Click Save.
GitHub will automatically create a CNAME file in your repository with your custom domain.
Step 2: Update Your DNS Settings
This step connects your domain to GitHub’s servers.
For Root Domain (yourdomain.com)
Add A records pointing to GitHub’s IP addresses:
| Type | Name | Value | TTL |
|---|---|---|---|
| A | @ | 185.199.108.153 | Default |
| A | @ | 185.199.109.153 | Default |
| A | @ | 185.199.110.153 | Default |
| A | @ | 185.199.111.153 | Default |
For Subdomain (www.yourdomain.com or blog.yourdomain.com)
Add a CNAME record pointing to your GitHub Pages domain:
| Type | Name | Value | TTL |
|---|---|---|---|
| CNAME | www | username.github.io | Default |
Replace username with your GitHub username.
Step 3: Wait for DNS Propagation
DNS changes can take anywhere from a few minutes to 48 hours to propagate worldwide. You can check if your DNS has updated using tools like WhatsMyDNS.net.
Step 4: Verify Your Setup
After propagation:
- Visit your custom domain in a browser.
- Your GitHub Pages site should load.
- GitHub will also automatically provision an SSL certificate for your domain, ensuring HTTPS support (this may take some time).
Troubleshooting Tips
- DNS Misconfiguration: Double-check your DNS records and remove conflicting or old entries.
- GitHub Pages Status: Confirm GitHub Pages is enabled and linked to the correct branch.
- SSL Not Active Yet: Give GitHub some time to provision the SSL certificate.
- Using a Subdomain? Make sure your CNAME points exactly to
username.github.io.
Summary
| Step | What to do |
|---|---|
| 1. Add custom domain in GitHub Pages settings | Enter your domain and save |
| 2. Update DNS records | Add A records (root domain) or CNAME (subdomain) pointing to GitHub |
| 3. Wait for DNS propagation | Typically minutes to hours |
| 4. Test your website | Visit your domain and check HTTPS |
Final Thoughts
Adding a custom domain to your GitHub Pages site gives your project a polished, professional presence on the web—perfect for portfolios, blogs, or documentation sites.
