GitHub Pages Tutorial: Free Hosting, Custom Domains, React

GitHub Pages is GitHub's free hosting for static websites. Push HTML, CSS and JavaScript to a repository, flip a setting, and it's live at https://username.github.io — with HTTPS included.

What it can and can't host

Can: static sites — plain HTML, portfolios, documentation, blogs from static site generators, and built React/Vue/Vite apps. (Static vs dynamic websites)

Can't: anything that needs a server running your code — a Node.js or Python backend, a database, server-side rendering, API routes, or storing form submissions. For those you need real hosting. (What is web hosting?)

GitHub's terms also say Pages isn't meant for commercial sites like online shops or SaaS products.

Option 1: publish a plain HTML site

Create a repository and add an index.html.
Go to Settings → Pages.
Under Build and deployment, choose Deploy from a branch, pick main and the / (root) folder.
Wait a minute. Your site is at https://username.github.io/repository-name/.

Name the repository username.github.io and the site lives at the root: https://username.github.io.

Option 2: deploy a React / Vite app with GitHub Actions

Apps that need a build step should be built by a workflow. In Settings → Pages, set the source to GitHub Actions, then add .github/workflows/pages.yml:

name: Deploy to Pages
on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v5
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v5

Check the current major versions of these actions in their repositories before copying — they're updated regularly. (GitHub Actions CI basics)

The two problems everyone hits

1. Blank page or missing CSS/JS

If your site is at username.github.io/my-app/, your app must know it lives under /my-app/. In Vite:

// vite.config.js
export default { base: '/my-app/' }

Without it, the browser looks for /assets/index.js at the domain root and gets a 404 — and you see a blank page. (React blank page after deploy)

2. 404 when refreshing a page

GitHub Pages doesn't know about your app's client-side routes. Visiting /my-app/settings directly asks for a file that doesn't exist. Common fixes: use hash-based routing (/#/settings), or copy index.html to 404.html in your build so unknown paths load the app. (Why refreshing gives a 404)

Custom domain

In Settings → Pages → Custom domain, enter www.yourdomain.com.
At your DNS provider, add a CNAME record for www pointing to username.github.io.
For the bare domain (yourdomain.com), add A records for GitHub's Pages IP addresses (listed in GitHub's docs) and/or AAAA records for IPv6.
Tick Enforce HTTPS once the certificate is issued.

Verify your domain in your GitHub account settings to stop anyone else claiming it on Pages. (How to connect a custom domain, DNS records explained)

Limits worth knowing

Sites should stay under about 1 GB; there's a soft bandwidth limit of roughly 100 GB per month.
Public repositories on free accounts; private repos need a paid plan.
No server-side code, no environment secrets at runtime — anything in your built files is public. (Keep API keys out of your app)

When to move on

When your project needs a backend, a database, user accounts or commercial use, it's outgrown Pages. (Vercel vs Netlify vs Cloudflare Pages, How to host a website for free)

EasySpawn is the next step after GitHub Pages: a server that runs your frontend, backend and Postgres database together, with HTTPS and daily backups. See how it works or join the waitlist.

GitHub Pages: Host a Website for Free From Your Repository