DEV Community

Profiterole
Profiterole

Posted on

How to Deploy a Static Website to GitHub Pages in 2026 (Step-by-Step)

#webdev #github #beginners #tutorial

Deploying a static website has never been easier — and in 2026, GitHub Pages remains one of the best free hosting options available. Whether you're launching a personal blog, a portfolio, or a project landing page, this guide walks you through everything from repo setup to custom domains.

What You'll Need

  • A GitHub account (free)
  • A static website (HTML/CSS/JS, or a static site generator output)
  • Git installed locally
  • Optionally: a custom domain

Step 1: Create a GitHub Repository

Log in to GitHub and create a new repository.

For a user/org site (served at https://yourusername.github.io/):

  • Name the repo exactly yourusername.github.io
  • This repo's main branch root becomes your site root

For a project site (served at https://yourusername.github.io/project-name/):

  • Name the repo anything (e.g., my-blog)
  • You'll configure the source branch/folder in settings

Make sure the repo is public (required for free GitHub Pages hosting).

Step 2: Push Your Static Files

If you're starting fresh locally:

git init
git remote add origin git@github.com:yourusername/your-repo.git
git add .
git commit -m "Initial deploy"
git push -u origin main
Enter fullscreen mode Exit fullscreen mode

If you're using a static site generator (Hugo, Jekyll, Eleventy, Astro, etc.), make sure you're pushing the built output — typically a _site/, dist/, or public/ folder — unless you're using GitHub Actions to build on push.

Step 3: Enable GitHub Pages

  1. Go to your repository on GitHub
  2. Click Settings → scroll down to Pages (left sidebar)
  3. Under Build and deployment, choose your source:
    • Deploy from a branch: pick main and either / (root) or /docs
    • GitHub Actions: use a workflow file to build and deploy (recommended for SSGs)
  4. Click Save

GitHub will give you a URL like https://yourusername.github.io/your-repo/ within a minute or two.

Tip for 2026: The GitHub Actions deployment path is now the default for new repos. It's more flexible and supports build steps without committing compiled files.

Step 4: Using GitHub Actions for Automated Builds

If your site needs a build step, create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci && npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist
      - uses: actions/deploy-pages@v4
Enter fullscreen mode Exit fullscreen mode

Adjust npm run build and the path to match your framework. Commit and push — GitHub will build and deploy automatically on every push to main.

Step 5: Custom Domain Setup

Want www.yoursite.com instead of yourusername.github.io/repo?

Add the domain in GitHub

  1. Settings → Pages → Custom domain
  2. Enter your domain (e.g., www.yoursite.com) and click Save
  3. GitHub creates a CNAME file in your repo root

Update your DNS

At your domain registrar, add these DNS records:

For an apex domain (yoursite.com):

A     @    185.199.108.153
A     @    185.199.109.153
A     @    185.199.110.153
A     @    185.199.111.153
Enter fullscreen mode Exit fullscreen mode

For a www subdomain:

CNAME  www  yourusername.github.io.
Enter fullscreen mode Exit fullscreen mode

DNS propagation takes 10 minutes to 48 hours. Once it propagates, GitHub will automatically provision a free TLS certificate via Let's Encrypt.

Enable HTTPS: After DNS propagates, tick "Enforce HTTPS" in Pages settings. This is essential — browsers flag HTTP sites as insecure.

Real-World Example

I use GitHub Pages to host Profiterole Blog, a personal finance blog built with Jekyll. The setup uses a GitHub Actions workflow to build on push — zero hosting cost, auto-deploys on every commit, and HTTPS out of the box.

The whole pipeline: write post → git push → GitHub Actions builds → live in ~2 minutes. No servers, no bills.

Troubleshooting Common Issues

Site shows 404

  • Check Settings → Pages — is the source branch/folder correct?
  • For project sites, make sure your links use the repo name as a base path (e.g., /my-blog/assets/style.css)
  • Wait 2–5 minutes after enabling Pages for the first time

Custom domain not working

  • Verify your CNAME file exists in the repo root and contains just the domain
  • Check DNS propagation with dig www.yoursite.com or an online DNS checker
  • Make sure you haven't accidentally deleted the CNAME file on a re-deploy

Changes not appearing

  • GitHub Actions may be queued — check the Actions tab for build status
  • Hard-refresh your browser (Ctrl+Shift+R) to bypass cache
  • Check if your workflow is targeting the right branch

Build fails in GitHub Actions

  • Check the Actions tab for the error log
  • Common culprit: Node/Ruby version mismatch. Pin your version in the workflow with node-version or ruby-version

HTTPS certificate not issuing

  • Confirm DNS is fully propagated first
  • Remove and re-add the custom domain in Settings → Pages to trigger a new cert request

Quick Reference Checklist

  • [ ] Repo is public
  • [ ] Static files are in the configured source branch/folder
  • [ ] Pages is enabled in Settings → Pages
  • [ ] For custom domains: CNAME file exists + DNS records updated
  • [ ] HTTPS enforced
  • [ ] GitHub Actions workflow deploys on push (if using a build step)

GitHub Pages is one of those tools that gets out of your way so you can focus on content. Once the pipeline is set up, deployments are invisible — push code, get a live site.

If this guide saved you some time, buy me a coffee ☕

Have a tricky GitHub Pages setup? Drop it in the comments — happy to help debug.

Top comments (0)