GitHub Pages — Setup & Custom Domain Guide

What is GitHub Pages?

GitHub Pages is a free static site hosting service that publishes files directly from a GitHub repository. It's perfect for open-source project documentation, personal portfolios, and simple websites. It's completely free with no bandwidth limits for public repositories.

Pros

• ▸Completely free for public repositories
• ▸No build server needed — deploy directly from repo
• ▸Built-in Jekyll support for blogs
• ▸Custom domain support with free SSL
• ▸GitHub Actions integration for complex builds
• ▸Excellent for open-source project documentation

Cons

• ▸Only static content — no server-side code
• ▸Soft bandwidth limit of 100GB/month
• ▸Builds can be slow (Jekyll)
• ▸Repository must be public for free hosting
• ▸Limited build environment compared to Vercel/Netlify

Best For

• ▸Personal portfolios and CVs
• ▸Open-source project documentation
• ▸Simple HTML/CSS/JS websites
• ▸Jekyll blogs

Setting Up GitHub Pages

• ▸Create a repository named yourusername.github.io (for personal site) or any repo name (for project site)
• ▸Push your HTML/CSS/JS files to the repo
• ▸Go to Settings → Pages
• ▸Select the branch to publish from (usually main or gh-pages)
• ▸Your site is live at yourusername.github.io

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci && npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Custom Domain DNS Configuration

For a subdomain (www or other)

Type:  CNAME
Name:  www
Value: yourusername.github.io.

For root domain (apex)

# GitHub Pages IP addresses (all four for redundancy)
Type: A  Name: @  Value: 185.199.108.153
Type: A  Name: @  Value: 185.199.109.153
Type: A  Name: @  Value: 185.199.110.153
Type: A  Name: @  Value: 185.199.111.153

Then in your GitHub repository, go to Settings → Pages → Custom Domain and enter your domain. GitHub will automatically provision an SSL certificate via Let's Encrypt.