How to Deploy a Static Site with GitHub Pages (Free)

In this tutorial, you'll learn about How to Deploy a Static Site with GitHub Pages (Free). We cover key concepts, practical examples, and best practices.

The Problem

You built a static site (HTML, Hugo, Jekyll, or React) and want to deploy it for free with a custom domain.

Quick Fix

1. Push your code to GitHub

Create a repo on GitHub, then:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/username/repo.git
git push -u origin main

2. Enable GitHub Pages

1. Go to your repo → Settings → Pages
2. Under Source, select Deploy from a branch
3. Choose main and / (root) (or /docs if your site is in a docs folder)
4. Click Save

3. Wait 1-2 minutes

Your site is live at https://username.github.io/repo/.

For a User/Organization Site

Name your repo username.github.io and it deploys to https://username.github.io/.

Custom Domain

1. Add a CNAME file to your repo root:

example.com

2. In your DNS provider, add a CNAME record pointing example.com to username.github.io
3. In GitHub Pages settings, enter your custom domain

GitHub Actions (for Build Tools)

For Hugo, React, or other build tools, add .github/workflows/deploy.yml:

on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm install && npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist