How to Deploy to GitHub Pages: Free Static Site Hosting Guide

What is GitHub Pages?

GitHub Pages is a free hosting service provided by GitHub for static websites. It's perfect for:

• Personal portfolios
• Project documentation
• Blogs (with Jekyll)
• Landing pages
• Demo sites

Key benefits:
- Completely free
- Custom domain support
- Automatic HTTPS
- Integrated with Git workflow

Quick Start: Deploy in 5 Minutes

Option 1: Deploy from a Branch

The simplest method for static HTML sites.

Step 1: Create a repository on GitHub

Step 2: Push your files

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

Step 3: Enable GitHub Pages
1. Go to repository Settings
2. Navigate to Pages (left sidebar)
3. Under "Source", select main branch
4. Select / (root) folder
5. Click Save

Step 4: Access your site
- URL format: https://username.github.io/repo-name/
- Wait 1-2 minutes for first deployment

Deploying Different Project Types

Static HTML/CSS/JS

The easiest—just push your files:

my-site/
├── index.html
├── styles.css
└── script.js

Make sure index.html is in the root or selected folder.

React (Create React App)

Step 1: Add homepage to package.json

{
  "homepage": "https://username.github.io/repo-name"
}

Step 2: Install gh-pages

npm install --save-dev gh-pages

Step 3: Add deploy scripts

{
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
}

Step 4: Deploy

npm run deploy

Vite (React/Vue/Svelte)

Step 1: Configure base in vite.config.js

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

Step 2: Add deploy script

{
  "scripts": {
    "deploy": "vite build && gh-pages -d dist"
  }
}

Step 3: Deploy

npm install --save-dev gh-pages
npm run deploy

Next.js (Static Export)

Step 1: Configure for static export (next.config.js)

module.exports = {
  output: 'export',
  basePath: '/repo-name',
  images: { unoptimized: true }
}

Step 2: Build and deploy

npm run build
# Deploy the 'out' folder to gh-pages branch

Using GitHub Actions (Recommended)

Automate deployment with GitHub Actions.

Step 1: Create .github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Step 2: Push to main

git push origin main

GitHub Actions automatically builds and deploys!

Custom Domain Setup

Step 1: Configure DNS

Add these records at your domain registrar:

For apex domain (example.com):

Type: A
Name: @
Values:
  185.199.108.153
  185.199.109.153
  185.199.110.153
  185.199.111.153

For subdomain (www.example.com):

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

Step 2: Add Custom Domain in GitHub

1. Go to repository Settings → Pages
2. Enter your domain in "Custom domain"
3. Check "Enforce HTTPS" (after DNS propagates)

Step 3: Add CNAME file

Create a CNAME file in your repo root:

example.com

For build tools, add to public folder or configure the build to include it.

Troubleshooting Common Issues

404 Error

Causes:
- Site not deployed yet (wait 1-2 minutes)
- Wrong branch/folder selected
- Missing index.html

Solutions:
1. Check Pages settings
2. Verify index.html exists
3. Check GitHub Actions logs

Site Shows README

Cause: GitHub renders README.md by default if no index.html

Solution: Add an index.html file

Broken Links/Assets

Cause: Relative paths don't work with repository subfolder

Solutions:
1. Use absolute paths starting with /repo-name/
2. Configure base path in build tools
3. Use relative paths from root: ./assets/image.png

CSS Not Loading

Cause: Path issues or caching

Solutions:
1. Check file paths in browser dev tools
2. Hard refresh (Cmd+Shift+R / Ctrl+Shift+R)
3. Verify base path configuration

GitHub Pages Limitations

Not supported:
- Server-side code (PHP, Node.js backend, etc.)
- Databases
- Dynamic content (without static generation)

Best Practices

1. Use GitHub Actions - Automate your deployments
2. Add .nojekyll - If not using Jekyll, add this empty file
3. Configure 404 page - Add a custom 404.html
4. Use custom domain - Looks more professional
5. Enable HTTPS - Always use secure connections

GitHub Pages vs Alternatives

Conclusion

GitHub Pages is perfect for free, simple static site hosting. It integrates beautifully with your Git workflow.

Key takeaways:
- Free hosting for static sites
- Easy setup from repository settings
- Use GitHub Actions for automation
- Custom domains supported

Start deploying your projects today!

Need Help Setting Up?

We help you deploy and configure your GitHub Pages site.

Get Help