How to Deploy a Static Site to GitHub Pages (Step-by-Step)

Mar 26, 2026

I spent hours configuring servers, setting up SSL certificates, and writing deployment scripts for my static website. Then I discovered GitHub Pages handles all of this automatically.

The problem? Most tutorials overcomplicate static site deployment. They talk about webhooks, custom servers, and manual configuration when GitHub Pages can deploy your site with a single push and serve it over a global CDN with HTTPS for free.

The Solution: Deploy in 5 Minutes

GitHub Pages gives your site a public URL, serves it over a global CDN with HTTPS, and auto-deploys when you push. I’ve been using it for years for my dev portfolio. I only push my clean working files to main, and GitHub Actions builds everything automatically.

Here’s how to do it.

Method 1: Quick Deploy for Simple Sites

If you have a simple HTML/CSS/JS site without a build step, this is the fastest way.

Step 1: Create Your Repository

# Create a new repository on GitHub or via CLI
gh repo create my-website --public --clone
cd my-website

Step 2: Add Your Static Files

Your directory structure should look like this:

my-website/
├── index.html          # Required: your homepage
├── css/
│   └── styles.css
├── js/
│   └── main.js
└── images/
    └── logo.png

Step 3: Push to GitHub

git add .
git commit -m "Initial website"
git push origin main

Step 4: Enable GitHub Pages

Go to repository Settings > Pages
Under “Source”, select Deploy from a branch
Select branch: main, folder: /(root)
Click Save

Your site is now live at: https://<username>.github.io/my-website

That’s it. Four steps and your static site is deployed.

Method 2: GitHub Actions Deploy (Recommended)

For sites with build processes like React, Vue, or Hugo, you need a more robust setup. GitHub Actions handles the build and deployment automatically.

Step 1: Create the Workflow File

Create a workflow file in your repository:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

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

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build site
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist    # Adjust to your build output folder

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Step 2: Enable GitHub Pages with GitHub Actions

Go to Settings > Pages
Under “Source”, select GitHub Actions
Your workflow will automatically run on push

Now every time you push to main, GitHub builds your site and deploys it automatically.

Method 3: Custom Domain Setup

I wanted my own domain instead of username.github.io. Here’s how to set that up.

Step 1: Add CNAME File

Create a CNAME file in your repository root (or build output folder):

www.yourdomain.com

No extension, just CNAME as the filename.

Step 2: Configure DNS

For apex domain (yourdomain.com), add four A records:

Type: A      Host: @     Value: 185.199.108.153
Type: A      Host: @     Value: 185.199.109.153
Type: A      Host: @     Value: 185.199.110.153
Type: A      Host: @     Value: 185.199.111.153

For www subdomain (recommended):

Type: CNAME  Host: www  Value: <username>.github.io

Step 3: Enable HTTPS

Wait for DNS propagation (up to 48 hours, usually faster)
Go to Settings > Pages > Custom domain
Verify your domain
Check Enforce HTTPS (may take a few minutes to activate)

GitHub automatically provisions SSL certificates for custom domains.

Troubleshooting Common Issues

Site Not Loading After Push

Cause: Build failed or wrong folder selected.

Fix: Check the Actions tab for build logs. Verify your Pages source folder matches your build output directory.

Custom Domain Shows 404

Cause: DNS not propagated or CNAME file missing.

Fix: Verify DNS with dig yourdomain.com. Ensure the CNAME file exists in your repository root.

CSS and Images Not Loading

Cause: Wrong relative paths for subdirectory deployment.

Fix: Use <base href="/"> in your HTML head, or configure your framework’s base path setting:

export default defineConfig({
  base: '/repo-name/',
})

HTTPS Not Available

Cause: DNS not verified or domain too recently added.

Fix: Wait up to 48 hours. Verify domain in Pages settings. The “Enforce HTTPS” checkbox appears once SSL is provisioned.

What I Learned

GitHub Pages eliminated my server management headaches. I push code, GitHub handles the rest. The free CDN, automatic HTTPS, and custom domain support make it the best option for static site deployment.

For simple sites, Method 1 gets you live in minutes. For modern frameworks, Method 2 with GitHub Actions is the way to go. And if you want a professional look, Method 3 adds your custom domain.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!