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.

Setting Up GitHub Pages With a Custom Domain

For a project site: push your static files to a gh-pages branch or the docs/ folder on main. Go to Settings → Pages → select source. Your site is live at <username>.github.io/<repo>.

For a user/organization site: create a repo named <username>.github.io. Push to main. Your site is live at https://<username>.github.io.

For a custom domain: add a CNAME record via your DNS provider pointing <yourdomain.com> to <username>.github.io. Create a CNAME file in your repo root with just your domain name: www.yourdomain.com. Or configure via Settings → Pages → Custom domain.

Enable HTTPS: GitHub Pages provides auto-renewing TLS certificates via Let's Encrypt. Check 'Enforce HTTPS' in Settings → Pages.

# Create a project site (branch-based)
git checkout -b gh-pages
echo '<h1>My Project</h1>' > index.html
git add . && git commit -m 'Initial site'
git push origin gh-pages

# Create a user site (repo-based)
mkdir myusername.github.io
cd myusername.github.io
git init
echo '<h1>Hello World</h1>' > index.html
git add . && git commit -m 'Initial site'
git remote add origin git@github.com:myusername/myusername.github.io.git
git push -u origin main

# Add a custom domain
echo 'www.myproject.com' > CNAME
git add CNAME
git commit -m 'Add custom domain'
git push

# Build with Jekyll (built-in)
echo 'theme: jekyll-theme-cayman' > _config.yml
git add . && git commit -m 'Add Jekyll config'
git push