How to Host a Static Website for Free with GitHub Pages

Posted on September 23, 2025 • 7 min read • 1,431 words

GitHub Development Helene

Share via

Link copied to clipboard

A guide to hosting a static website for free with GitHub Pages, step by step.

On this page

How to Host a Static Website for Free with GitHub Pages — Photo by Helene Hemmerter

I. Why Choose GitHub Pages to Host a Static Website?

GitHub Pages is a free service provided by GitHub to host static-only websites (HTML, CSS, JavaScript), with no backend or dynamic server.
It is particularly well-suited for portfolios, project documentation, or simple blogs, especially for developers familiar with GitHub.
The service includes a free .github.io domain, supports custom domains, and has built-in HTTPS.
Limitations: max size ~1 GB, bandwidth ~100 GB/month, no support for PHP, databases, or other server-side languages.

II. Prerequisites and Initial Setup

Create a GitHub account (if you don’t already have one).
Create a public repository named USERNAME.github.io for a user or organization site, or a generic repository for a project site.
Add initial files like README.md or index.html.
Make sure GitHub Actions is enabled to allow build workflows (e.g., Jekyll generation).

Before deploying a static site with GitHub Pages, you need to configure the repository. Here’s how:

1. Create a GitHub Account

If you don’t yet have a GitHub account:

Go to https://github.com/join
Sign up using a valid email address.
Choose a username (important, as it will appear in your site’s URL for a user site).

2. Create a New Repository

Go to https://github.com/new to create a new repository:

Two types of repositories are possible:

Site Type	Repository Name	Public Site URL
User/Organization Site	`USERNAME.github.io`	`https://USERNAME.github.io/`
Project Site	Any name, e.g. `my-project`	`https://USERNAME.github.io/my-project/`

The repository must be public to use GitHub Pages for free.
You can check “Add a README file” to initialize the repository.

💡 For personal sites, the repository must match exactly USERNAME.github.io.

3. Add Initial Files

Two options:

Use the GitHub editor to add a README.md or a simple index.html (e.g., Hello World!)
Or clone the repo locally with git clone, add your static files, and push them.

Minimal example of index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My First GitHub Pages Site</title>
  </head>
  <body>
    <h1>Hello GitHub Pages!</h1>
  </body>
</html>

4. Make Sure GitHub Actions is Enabled

GitHub Pages works without Actions if you’re only deploying simple static files.

However, it is highly recommended to enable GitHub Actions if:

You are using a static site generator such as Jekyll, Hugo, Astro, Gatsby, etc.
You want to automate the build process (npm run build, hugo, etc.) on each change.

To verify or enable GitHub Actions:

Go to the Settings tab of your repository.
Click Actions > General in the sidebar.
Under “Actions permissions”, make sure “Allow all actions and reusable workflows” (or “Allow select actions”) is enabled.
You can then add a workflow YAML file inside .github/workflows/.

Example file: .github/workflows/deploy.yml

Example 1: Standard Deployment (HTML/CSS/JS, Astro, Vite…)

📄 .github/workflows/deploy.yml

name: Deploy static site to GitHub Pages

on:
  push:
    branches:
      - main  # Trigger on every push to main

permissions:
  contents: write  # Required to publish to gh-pages

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Build the site
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist  # Replace with ./public if needed

Suitable for modern stacks like Astro, Vite, static React, etc.
Automatically deploys the dist/ folder on every push to main.

Example 2: Deployment with Hugo

📄 .github/workflows/deploy.yml

name: Deploy Hugo site to GitHub Pages

on:
  push:
    branches:
      - main  # Trigger on each push to main

permissions:
  contents: write  # Required to push to gh-pages

jobs:
  build-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout source
        uses: actions/checkout@v4

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.124.1'  # Specify your Hugo version

      - name: Build Hugo site
        run: hugo --minify

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

This workflow automatically builds your Hugo site and publishes the public/ folder to the gh-pages branch.
No SSH key setup is required, the GitHub token is sufficient.

Practical Example

If you’re building a blog with Hugo, you can create a GitHub Action that:

runs the hugo command to generate the static site,
and pushes the result to the gh-pages branch.

This allows for automatic deployment on every git push.

5. Visual Summary

Step	Required Action
GitHub Account	Create an account on github.com
Site Type	`USERNAME.github.io` or custom repo name
Initial Content	Add `index.html`, `README.md`, etc.
Enable GitHub Actions	Ensure actions are allowed in repository settings
Ready for Pages	Enable GitHub Pages under Settings > Pages

III. Deployment: Step by Step

Clone the repository locally
Add your static files
Commit & push your changes
Enable GitHub Pages via the interface
Access your live site

Once your repository is ready and configured, here’s how to publish your static site using GitHub Pages:

1. Clone the Repository Locally

Use this command in your terminal:

git clone https://github.com/USERNAME/USERNAME.github.io

Replace USERNAME with your actual GitHub username.
This structure is used for a user or organization site.

For a project site, use:

git clone https://github.com/USERNAME/project-name

Replace project-name with your actual repository name.

2. Add Your Static Files

Inside the cloned directory, add your site content:

Required index.html
CSS files (style.css)
JavaScript files (script.js)
Assets (images, fonts, icons, etc.)

Typical structure:

my-site/
├── index.html
├── style.css
├── script.js
└── img/
    └── logo.png

3. Commit & Push Changes

Once your files are added, run:

git add --all
git commit -m "Initial commit"
git push origin main

If your default branch is master, use:
git push origin master

4. Enable GitHub Pages via the Interface

Open your repository on github.com
Go to the Settings tab
Click on Pages in the left menu
Under Build and deployment, choose:
- Source: Deploy from a branch
- Branch: main (or master)
- Folder: / (root) if your files are in the root
Click Save

A success message will show the URL of your site.

5. Access Your Published Site

Site Type	Auto-generated URL
User Site	`https://USERNAME.github.io/`
Project Site	`https://USERNAME.github.io/project-name/`

Future changes will appear at this URL after each git push.

Note: it may take up to 10 minutes for the first deployment to appear.
If changes don’t show, try clearing your browser cache.

IV. Advanced Features: Jekyll, Customization, Custom Domain

GitHub Pages supports Jekyll, a popular static site generator based on Ruby and Markdown. It automatically converts .md files to HTML.

📚 Reference: Jekyll – Wikipedia, Kinsta – GitHub Pages Guide

Using Another Generator

If you prefer Hugo, Astro, Gatsby, or others:

Generate your site locally into a folder like dist/ or public/
Push the generated files to a branch (commonly gh-pages)
Add a blank .nojekyll file to the root to disable Jekyll processing

You can automate this with GitHub Actions.

📚 Reference: GitHub Docs – Disabling Jekyll

Themes & Customization

GitHub Pages offers built-in themes that can be enabled via the interface or _config.yml.

You can also:

Start from scratch for full control of design
Use or adapt existing Jekyll themes

📚 Reference: GitHub Pages, Kinsta

Using a Custom Domain

You can link a personal domain easily:

Go to Settings > Pages
Enter your domain in Custom domain
Configure DNS records (A or CNAME) with your domain provider

GitHub Pages enables HTTPS via Let’s Encrypt automatically.

📚 Reference: GitHub Docs – Custom Domains, DEV.to, LinkedIn

V. Use Cases and Comparison Table

A. Common Use Cases

Developer or designer portfolio (HTML/CSS/JS)
Open source project documentation
Static blog using Jekyll
Landing page for a GitHub project

B. Quick Comparison

Objective	GitHub Pages (Free)	Main Limitations
Static site (HTML/CSS/JS)	✅ Very easy to deploy	❌ No dynamic backend
Docs or wiki	✅ Jekyll built-in	❌ Not ideal for heavy content or traffic
Custom domain & HTTPS	✅ Native support	–
CI/CD integration via GitHub Actions	✅ Auto-deploy on push	–
Forms or dynamic features	❌ Needs third-party services (e.g. Formspree)	❌ No PHP or server-side support

VI. Conclusion

GitHub Pages is a free, reliable, and easy-to-use solution for hosting static websites. It’s ideal for portfolios, personal blogs, project documentation, and simple landing pages.

With native Jekyll support, GitHub Actions integration, and easy custom domain setup, it’s a great entry point to publish your web projects with zero cost.

For advanced use cases (backend, databases, dynamic content), consider using AWS S3, Netlify, or Vercel.

🔗 Useful Resources

How to Host a Static Website for Free with AWS S3

CSS Color Palette: How to Choose and Combine Colors Effectively

We work with you!