GitHub Pages — The Custom Domain That Went to the Wrong Server

GitHub Pages is the simplest way to host a static site: push code, get a URL. It powers documentation sites, personal portfolios, project landing pages, and even full static blogs (via Jekyll). The simplicity is the killer feature: there's no server to manage, no CI/CD pipeline to configure, no hosting bill. But simplicity has edge cases: the CNAME file, 404 handling, and custom domain DNS propagation. This guide covers setup, the custom domain incident that took down a product launch, and how to avoid the most common Pages pitfalls.

What Is GitHub Pages and Why Use It?

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files directly from a repository on GitHub, optionally runs the files through a build process, and publishes a website. It's free, integrates with your existing Git workflow, and supports custom domains and HTTPS. For production use, it's ideal for documentation sites, project landing pages, personal portfolios, and even small business sites. The key advantage is zero server management: you push code, and GitHub handles deployment. However, it's not a dynamic hosting platform — no server-side processing, databases, or backend logic. If you need those, look elsewhere. For static content, it's a no-brainer.

name: Deploy to GitHub Pages
on:
  push:
    branches: ["main"]
  workflow_dispatch:
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: "pages"
  cancel-in-progress: false
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/deploy-pages@v4

Setting Up Your Repository for GitHub Pages

To host a site, you need a repository. For a user or organization site, name the repo <username>.github.io. For project sites, any name works, and the site will be at <username>.github.io/<repo-name>. Enable Pages in the repo Settings > Pages. Choose the source branch (usually main or gh-pages) and optionally a /docs folder. For modern static site generators (Jekyll, Hugo, etc.), GitHub Pages can build your site automatically. For plain HTML, just push your files. Important: if you use a custom domain, add a CNAME file in the root of your publishing source with your domain (e.g., example.com). Also configure your DNS provider with a CNAME record pointing to <username>.github.io.

# Create a new repository for a user site
git init my-site
cd my-site
echo "<h1>Hello World</h1>" > index.html
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/username.github.io.git
git push -u origin main

Using a Static Site Generator with GitHub Pages

GitHub Pages natively supports Jekyll, but you can use any static site generator (Hugo, Next.js, Astro) by building locally and pushing the output, or using GitHub Actions to build and deploy. For Jekyll, just push your source files; GitHub builds them automatically. For others, you need a workflow. The advantage of a generator: templating, Markdown support, asset pipeline, and SEO optimization. For production, I recommend using a CI/CD pipeline to ensure builds are reproducible and tested. Avoid committing the built _site folder — let the CI generate it. This prevents merge conflicts and keeps the repo clean.

name: Deploy Hugo site to Pages
on:
  push:
    branches: ["main"]
  workflow_dispatch:
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: '0.124.0'
      - name: Build
        run: hugo --minify
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public
  deploy:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/deploy-pages@v4

Custom Domains and HTTPS

GitHub Pages supports custom domains with automatic HTTPS via Let's Encrypt. To set up, add a CNAME file to your repository's root (or configure in Settings > Pages > Custom domain). Then update your DNS: for apex domains (e.g., example.com), add an A record pointing to GitHub's IPs (185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153). For subdomains (e.g., www.example.com), add a CNAME record pointing to <username>.github.io. After configuration, GitHub provisions an SSL certificate automatically. This can take up to an hour. If you use a CDN like Cloudflare, disable the proxy (orange cloud) for the DNS record, or use a full strict SSL mode.

example.com.    A     185.199.108.153
example.com.    A     185.199.109.153
example.com.    A     185.199.110.153
example.com.    A     185.199.111.153
www.example.com. CNAME username.github.io.

Enforcing HTTPS and Redirects

GitHub Pages automatically redirects HTTP to HTTPS if you have a custom domain and HTTPS is enabled. You can enforce HTTPS in Settings > Pages > Enforce HTTPS. This is critical for production: without it, users may access your site over insecure HTTP. Additionally, you can set up redirects using a _redirects file (Netlify-style) or a staticwebapp.config.json for Azure Static Web Apps, but GitHub Pages has limited redirect support. For advanced redirects, use a meta refresh in HTML or a JavaScript redirect. For SEO, prefer server-side redirects; since GitHub Pages doesn't support them natively, consider using a service like Cloudflare Workers or Netlify instead.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="refresh" content="0; url=https://example.com/new-page">
  <link rel="canonical" href="https://example.com/new-page">
</head>
<body>
  <p>Redirecting to <a href="https://example.com/new-page">new page</a>.</p>
</body>
</html>

Using GitHub Actions for Advanced Deployments

GitHub Actions gives you full control over the build and deploy process. You can run tests, lint, build, and then deploy. The official actions/deploy-pages action handles deployment to the github-pages environment. For production, always pin action versions to a specific commit SHA to avoid supply chain attacks. Also, use environment secrets for API keys or tokens. A common pattern: build on push to main, deploy to a staging environment on a develop branch, and promote to production via a workflow dispatch. This mirrors a real CI/CD pipeline.

name: Deploy to Staging
on:
  push:
    branches: ["develop"]
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: npm ci && npm run build
      - name: Deploy to Pages
        uses: actions/deploy-pages@v4
        with:
          artifact_name: staging-site

Handling 404 Pages and SEO

GitHub Pages automatically serves a 404 page if a file is not found. You can customize it by adding a 404.html file to the root of your publishing source. For SEO, ensure your 404 page is helpful and includes a link to the homepage. Also, create a sitemap.xml and robots.txt to guide search engines. For single-page applications (SPAs), you need to handle client-side routing: create a 404.html that redirects to index.html with the requested path as a hash or query parameter. This is a common pitfall — without it, direct links to SPA routes return 404.

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>404 - Page Not Found</title>
  <script>
    // SPA fallback: redirect to index with the path as a query param
    sessionStorage.redirect = location.href;
    location.href = '/index.html?redirect=' + encodeURIComponent(location.pathname);
  </script>
</head>
<body>
  <h1>404</h1>
  <p>Page not found. <a href="/">Go home</a>.</p>
</body>
</html>

Performance Optimization and Caching

GitHub Pages serves static files with strong caching headers (Cache-Control: max-age=600 for HTML, 1 year for assets with hashed filenames). For production, optimize images (use WebP, compress), minify CSS/JS, and enable gzip compression (GitHub Pages does this automatically). Use a CDN like Cloudflare in front of GitHub Pages for additional caching and DDoS protection. However, be aware that GitHub Pages has a bandwidth limit of 100 GB per month (for free accounts). For high-traffic sites, consider a dedicated CDN or static hosting provider. Also, use lazy loading for images and defer non-critical scripts.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Optimized Site</title>
  <link rel="preload" href="/styles.min.css" as="style">
  <link rel="stylesheet" href="/styles.min.css">
  <script defer src="/scripts.min.js"></script>
</head>
<body>
  <img src="/hero.webp" alt="Hero" loading="lazy" width="1200" height="600">
</body>
</html>

Troubleshooting Common GitHub Pages Issues

Common issues: site not updating (check Actions tab for build failures), custom domain not resolving (DNS propagation can take 24h, verify A records), HTTPS not provisioning (ensure DNS is correct and not proxied through Cloudflare), 404 errors (check file paths and case sensitivity — GitHub Pages is case-sensitive), and build failures (check your static site generator's logs). For Jekyll, ensure your Gemfile and _config.yml are correct. For Actions, review the workflow logs. If your site is stuck on an old version, trigger a manual redeploy via the Actions tab or push an empty commit.

# Trigger a redeploy by pushing an empty commit
git commit --allow-empty -m "Trigger redeploy"
git push

When Not to Use GitHub Pages

GitHub Pages is not suitable for every project. Avoid it if you need server-side processing (PHP, Node.js, Python), a database, user authentication, or real-time features. Also, if you require custom redirects (301/302), advanced caching rules, or a Web Application Firewall (WAF), look elsewhere. For e-commerce, membership sites, or any site handling sensitive data, GitHub Pages lacks the necessary security controls. Finally, if your site exceeds 1 GB in size or 100 GB monthly bandwidth, you'll hit limits. For those cases, consider Vercel, Netlify, AWS S3 + CloudFront, or a VPS.

GitHub Pages:
- Free, simple, Git-integrated
- Static only, no backend
- 1 GB repo limit, 100 GB bandwidth
- Limited redirects, no WAF

Alternatives:
- Netlify: Forms, functions, redirects, 100 GB bandwidth free
- Vercel: Serverless functions, edge caching, analytics
- AWS S3 + CloudFront: Scalable, full control, pay-as-you-go