Configure Custom Domain and Sub-domain with GitHub Pages in Cloudflare

The Comprehensive Guide to Mapping Custom Domains and Sub-domains to GitHub Pages via Cloudflare

Published by RelMusic Cloud Infrastructure Division | Production Ready for 2026 Standards

Hosting static websites, documentation portals, or enterprise web ecosystems on GitHub Pages provides unmatched reliability and seamless version control. However, using the default username.github.io URL structure lacks professional branding. Integrating a custom apex domain (e.g., relmusic.com) or a dedicated sub-domain (e.g., blog.relmusic.com) through Cloudflare supercharges your web property with lightning-fast CDN caching, robust DDoS protection, and automated SSL/TLS encryption.

This technical guide details the precise end-to-end configuration required to bridge GitHub Pages with Cloudflare DNS management.

1. Understanding GitHub Pages DNS Requirements

Before configuring Cloudflare, it is crucial to understand how GitHub Pages recognizes custom domains. GitHub requires either an apex domain redirect or a direct CNAME pointer matching your GitHub Pages username repository.

Apex Domains vs. Sub-domains

• Apex Domains (Root Domain like relmusic.github.io mapped to example.com): Requires configuring GitHub's official IP addresses (185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153) as A records, alongside a CNAME record for www.
• Sub-domains (e.g., blog.example.com or docs.example.com): Requires a simple CNAME record pointing directly to your GitHub Pages default address (username.github.io).

2. Step-by-Step Configuration in Cloudflare Dashboard

Follow these steps to route your domain traffic correctly through Cloudflare DNS:

Step 1: Add Your Domain to Cloudflare

Log in to your Cloudflare account, click Add a Site, enter your domain name, and select a free or paid plan. Update your domain registrar's nameservers to point to the provided Cloudflare nameservers.

Step 2: Configure DNS Records for Sub-domains

For a sub-domain such as blog.relmusic.com, add a CNAME record in the Cloudflare DNS manager:

• Type: CNAME
• Name: blog (or your chosen sub-domain prefix)
• Target: relmusic.github.io
• Proxy Status: Proxied (Orange Cloud) or DNS Only (Grey Cloud) during initial GitHub handshake.

Step 3: Configure DNS Records for Apex Domains

If you are mapping the root domain (relmusic.com), set up the four GitHub IP A records:

3. Establishing the CNAME File in Your GitHub Repository

GitHub needs verification that you own the custom domain. In your GitHub repository root directory, create a file named CNAME (without any file extension) containing only your custom domain name (e.g., blog.relmusic.com or relmusic.com).

Once pushed to your repository, navigate to your GitHub repository settings under Pages, and enter your custom domain into the designated custom domain field.

4. Optimizing SSL/TLS Settings in Cloudflare

To avoid SSL certificate errors (such as ERR_CERT_COMMON_NAME_INVALID) between Cloudflare and GitHub Pages:

• Set your Cloudflare SSL/TLS encryption mode to Full or Full (strict).
• Enable Always Use HTTPS to automatically redirect insecure HTTP requests.
• Ensure the Enforce HTTPS checkbox is selected in your GitHub Pages settings once the custom certificate check turns green.

External Authoritative References

• GitHub Pages Official Custom Domain Documentation
• Cloudflare DNS Management Guide
• Let's Encrypt Free SSL/TLS Certificates
• W3C Web Standards Specifications
• MDN Web Docs HTTP Overview
• IETF Network Working Group RFC Standards
• Cloudflare Learning Center: What is DNS?
• GitHub Platform & Version Control Repository
• GitHub Pages Static Hosting Infrastructure
• ICANN Domain Name System Policy Guidelines

Internal Pillar Links

• RelMusic Home Pillar & Resource Center
• Cybersecurity & Zero-Trust Cloud Architectures
• Database Management & Cloud Hosting Architectures
• Enterprise AI Integration & Machine Learning Pipelines