How to Connect a Custom Domain on Cloudflare to GitHub Pages Without Downtime


Connecting a custom domain to your GitHub Pages site is a crucial step in building a professional online presence. While the process is straightforward, a misstep can lead to frustrating hours of downtime or SSL certificate errors, making your site inaccessible. This guide provides a meticulous, step-by-step walkthrough to migrate your GitHub Pages site to a custom domain managed by Cloudflare without a single minute of downtime. By following these instructions, you will ensure a smooth transition that maintains your site's availability and security throughout the process.

In This Guide

What You Need Before Starting

Before you begin the process of connecting your domain, you must have a few key elements already in place. Ensuring you have these prerequisites will make the entire workflow seamless and predictable.

First, you need a fully published GitHub Pages site. This means your repository is configured correctly, and your site is accessible via its default `username.github.io` or `organization.github.io` URL. You should also have a custom domain name purchased and actively managed through your Cloudflare account. Cloudflare will act as your DNS provider and security layer. Finally, you need access to both your GitHub repository settings and your Cloudflare dashboard to make the necessary configuration changes.

Step 1: Preparing Your GitHub Pages Repository

The first phase of the process happens within your GitHub repository. This step tells GitHub that you intend to use a custom domain for your site. It is a critical signal that prepares their infrastructure for the incoming connection from your domain.

Navigate to your GitHub repository on the web and click on the "Settings" tab. In the left-hand sidebar, find and click on "Pages". In the "Custom domain" section, input your full domain name (e.g., `www.yourdomain.com` or `yourdomain.com`). It is crucial to press Enter and then save the change. GitHub will now create a commit in your repository that adds a `CNAME` file containing your domain. This file is essential for GitHub to recognize and validate your custom domain.

A common point of confusion is whether to use the root domain (`yourdomain.com`) or the `www` subdomain (`www.yourdomain.com`). You can technically choose either, but your choice here must match the DNS configuration you will set up in Cloudflare. For now, we recommend starting with the `www` subdomain as it simplifies some aspects of the SSL certification process. You can always change it later, and we will cover how to redirect one to the other.

Step 2: Configuring Your DNS Records in Cloudflare

This is the most technical part of the process, where you point your domain's traffic to GitHub's servers. DNS, or Domain Name System, is like the internet's phonebook, and you are adding a new entry for your domain. We will use two primary methods: CNAME records for subdomains and A records for the root domain.

First, let's configure the `www` subdomain. Log into your Cloudflare dashboard and select your domain. Go to the "DNS" section from the top navigation. You will see a list of existing DNS records. Click "Add record". Choose the record type "CNAME". For the "Name", enter `www`. In the "Target" field, you must enter your GitHub Pages URL: `username.github.io` (replace 'username' with your actual GitHub username). The proxy status should be "Proxied" (the orange cloud icon). This enables Cloudflare's CDN and security benefits. Click "Save".

Next, you need to point your root domain (`yourdomain.com`) to GitHub Pages. Since a CNAME record is not standard for root domains, you must use A records. GitHub provides specific IP addresses for this purpose. Create four separate "A" records. For each record, the "Name" should be `@` (which represents the root domain). The "Target" will be one of the following four IP addresses:

Set the proxy status for all four to "Proxied". Using multiple A records provides load balancing and redundancy, making your site more resilient.

Understanding DNS Propagation

After saving these records, there will be a period of DNS propagation. This is the time it takes for the updated DNS information to spread across all the recursive DNS servers worldwide. Because you are using Cloudflare, which has a very fast and global network, this propagation is often very quick, sometimes under 5 minutes. However, it can take up to 24-48 hours in rare cases. During this time, some visitors might see the old site while others see the new one. This is normal and is the reason our method is designed to prevent downtime—both the old and new records can resolve correctly during this window.

Step 3: Enforcing HTTPS on GitHub Pages

Once your DNS has fully propagated and your site is loading correctly on the custom domain, the final step is to enable HTTPS. HTTPS encrypts the communication between your visitors and your site, which is critical for security and SEO.

Return to your GitHub repository's Settings > Pages section. Now that your DNS is correctly configured, you will see a new checkbox labeled "Enforce HTTPS". Before this option becomes available, GitHub needs to provision an SSL certificate for your custom domain. This process can take from a few minutes to a couple of hours after your DNS records have propagated. You must wait for this option to be enabled; you cannot force it.

Once the "Enforce HTTPS" checkbox is available, simply check it. GitHub will now automatically redirect all HTTP requests to the secure HTTPS version of your site. This ensures that your visitors always have a secure connection and that you do not lose traffic to insecure links. It is a vital step for building trust and complying with modern web standards.

Step 4: Troubleshooting Common SSL Propagation Issues

Sometimes, things do not go perfectly according to plan. The most common issues revolve around SSL certificate provisioning. Understanding how to diagnose and fix these problems will save you a lot of stress.

If the "Enforce HTTPS" checkbox is not appearing or is grayed out after a long wait, the most likely culprit is a DNS configuration error. Double-check that your CNAME and A records in Cloudflare are exactly as specified. A single typo in the target of the CNAME record will break the entire chain. Ensure that the domain you entered in the GitHub Pages settings matches the DNS records you created exactly, including the `www` subdomain if you used it.

Another common issue is "mixed content" warnings after enabling HTTPS. This occurs when your HTML page is loaded over HTTPS, but it tries to load resources like images, CSS, or JavaScript over an insecure HTTP connection. The browser will block these resources. To fix this, you must ensure all links in your website's code use relative paths (e.g., `/assets/image.jpg`) or absolute HTTPS paths (e.g., `https://yourdomain.com/assets/style.css`). Never use `http://` in your resource links.

Best Practices for a Robust Setup

With your custom domain live and HTTPS enforced, your work is mostly done. However, adhering to a few best practices will ensure your setup remains stable, secure, and performs well over the long term.

It is considered a best practice to set up a redirect from your root domain to the `www` subdomain or vice-versa. This prevents duplicate content issues in search engines and provides a consistent experience for your users. You can easily set this up in Cloudflare using a "Page Rule". For example, to redirect `yourdomain.com` to `www.yourdomain.com`, you would create a Page Rule with the URL pattern `yourdomain.com/*` and a setting of "Forwarding URL" (Status Code 301) to `https://www.yourdomain.com/$1`.

Regularly monitor your DNS records and GitHub settings, especially after making other changes to your infrastructure. Avoid removing the `CNAME` file from your repository manually, as this is managed by GitHub's settings panel. Furthermore, keep your Cloudflare proxy enabled ("Proxied" status) on your DNS records to continue benefiting from their performance and security features, which include DDoS protection and a global CDN.

By meticulously following this guide, you have successfully connected your custom domain to GitHub Pages using Cloudflare without any downtime. You have not only achieved a professional web address but have also layered in critical performance and security enhancements. Your site is now faster, more secure, and ready for a global audience.

Ready to leverage the full power of your new setup? The next step is to dive into Cloudflare Analytics to understand your traffic and start making data-driven decisions about your content. Our next guide will show you exactly how to interpret this data and identify new opportunities for growth.



.