Skip to main content

Set up GitHub Pages with Cloudflare and a Custom Domain

GitHub Pages is a web hosting service provided by GitHub, offering a straightforward way to serve static websites directly from your GitHub repository. Essentially, it allows you to showcase your projects, whether they be personal blogs, portfolios, or small business sites, without the need for complex server configurations.

What makes GitHub Pages even more versatile is its compatibility with Cloudflare, a content delivery network (CDN) and internet security service. This tutorial will walk you through the process of harnessing the power of GitHub Pages and Cloudflare to set up a scalable, secure, and performant website.

Why choose GitHub Pages and Cloudflare?​

  • Completely Free Hosting: GitHub Pages allows you to host your static website at no cost. Cloudflare, while also free, brings additional benefits to the table. Note that charges may apply if you opt for a private repository.

  • Scalable: Your website can grow with you. GitHub Pages and Cloudflare offer scalable solutions, ensuring your site remains accessible no matter how popular it becomes.

  • Reliable and Performant: Experience enterprise-level hosting reliability without the hefty price tag. Leverage Cloudflare's global CDN network for accelerated content delivery, ensuring fast load times for visitors worldwide.

  • Secure by Default: Cloudflare's Universal SSL ensures secure HTTPS connections, enhancing overall security and capitalizing on the performance benefits of the latest web protocols.

Prerequisites​

  • GitHub account
  • Cloudflare account
  • Registered domain name

Configure your Domain​

Securing your custom domain is an essential step in assigning a public name to your website. First things first, if you haven't already, purchase your new domain name from a domain registrar like Namecheap.

After obtaining your domain, make sure to add it to your Cloudflare account for efficient DNS management. Navigate to the DNS → Records section in your Cloudflare dashboard. This is where you'll find the nameservers needed for the subsequent steps. Note that the actual names may differ, but they are typically displayed as:

aitana.ns.cloudflare.com
tanner.ns.cloudflare.com

Now, you'll need to do a bit of manual configuration. In your domain registrar's admin panel, locate the option to change or update your domain's nameservers. Point them to the Cloudflare nameservers you found earlier. This connection is essential for Cloudflare to manage your domain effectively. For a comprehensive guide on configuring nameservers, please refer to the "provider-specific instructions" section in Cloudflare's setup documentation.

In the case of Namecheap, the admin panel section will look something like this:

Namecheap Nameservers

Configure Cloudflare​

Configure DNS​

Setting up your DNS is a vital step in making your website accessible. In your Cloudflare dashboard under DNS → Records, point your apex domain to GitHub Pages by creating A records for the following IP addresses.

Note

The IP addresses may change in the future. For the most current list, refer to the official GitHub documentation.

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Ensure all entries are set to proxied to fully leverage Cloudflare and benefit from enhanced security and performance. Additionally, it's recommended to also add a CNAME entry for the www subdomain.

Example for rikublock.dev. Your configuration should resemble the image below:

Cloudflare DNS Records

To confirm your DNS record configuration (and proxy status), replace rikublock.dev with your apex domain in the following commands. Confirm that the results return IP addresses that belong to Cloudflare.

dig rikublock.dev +noall +answer -t A
dig www.rikublock.dev +noall +answer -t A

Configure SSL​

Note

GitHub Pages relies on letsencrypt to automatically issue trusted certificates for custom user domains, ensuring secure traffic encryption. However, when using Cloudflare in a proxied setup, letsencrypt encounters challenges in verifying domain ownership, causing certificate generation to fail. In such cases, GitHub will provide a self-signed certifcate, which is sufficient as long as the Cloudflare SSL mode is not set to strict.

In your Cloudflare dashboard, navigate to SSL/TLS → Overview. Here, set the encryption mode to "Full". Do not select "Full (strict)" as it won't work correctly with GitHub Pages.

Cloudflare Mode

Optionally, consider turning on the following features under SSL/TLS → Edge Certificates for improved security:

  • "Always Use HTTPS": This ensures that your visitors always access the secure HTTPS version of your website.
  • "Automatic HTTPS Rewrites": Automatically corrects insecure resources, further enhancing your website's security.

Configure Github​

If you haven't already, let's start by creating a new repository on GitHub. This is your digital storage space for all your website's contents, similar to setting up a folder for your project. You can choose any name for the repository. Remember, for free hosting, make your repository public. If privacy is a concern, you can choose a private repository, but that comes with a small cost.

GitHub Pages is tailored for static content and seamlessly integrates with various static site generators, such as Docusaurus or Jekyll. These tools streamline the website-building process, offering a simple way to create your site. If you're interested in exploring additional options, a comprehensive overview of generators awaits you here.

There are two ways to publish a website on GitHub Pages: either source it directly from a branch or utilize a GitHub Action workflow. Opting for a workflow is the preferred choice due to its numerous benefits.

Deployment Workflow​

The website building and deployment process can be automated with a GitHub workflow. The following example workflow is triggered whenever changes are pushed to the master branch. The initial step involves building the website pages through the execution of the build script command. Subsequently, the resulting artifacts located in the build/ folder are uploaded and seamlessly deployed to the GitHub-hosted page. Depending on your specific setup, minor adjustments to the workflow may be required.

.github/workflows/deploy.yml
name: Deploy with GitHub Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches:
      - master

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup node
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Build website
        run: |
          yarn install
          yarn build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: "build/"

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-22.04
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Configure Pages​

In your repository, head to the Settings tab and find the Pages option on the left-side menu. Once there, set the source for your pages to "GitHub Actions". This ensures that the artifacts from your previously installed workflow will be utilized for deployments.

Afterward, proceed to configure the custom domain to match your apex domain (e.g. rikublock.dev) and save your changes. It's important to note that this action triggers a DNS check, which is anticipated to fail initially due to the Cloudflare proxy setup. You can simply ignore the notification.

For example, configuring rikublock.dev would resemble the following:

Github Pages Settings

Conclusion​

In conclusion, the trio of GitHub Pages, Cloudflare, and a static site generator offers a swift, secure, and cost-free solution for hosting static websites with the added benefit of custom domain support. The straightforward and efficient setup makes it an excellent choice for various projects.

Finally, if you're intrigued by this setup, Cloudflare offers a similar service that is certainly worth exploring: Cloudflare Pages. It provides another avenue for seamless deployment and hosting of fast websites.