Published February 27, 2026 · by SpunkArt · 14 min read
GitHub Pages is the best free hosting platform for static websites. Zero cost, zero ads, free HTTPS, custom domain support, and a global CDN backed by Microsoft's infrastructure. Every site in the Spunk Network runs on GitHub Pages, and this guide shows you exactly how to do the same.
Whether you are deploying a portfolio, blog, documentation site, landing page, or full web application with a static frontend, this step-by-step guide covers everything from creating your first repository to configuring custom domains and setting up automated deployments.
GitHub Pages is a free static site hosting service provided by GitHub. It takes HTML, CSS, and JavaScript files directly from a repository, optionally runs them through a build process, and publishes them as a website. Every GitHub account gets one user site at username.github.io and unlimited project sites at username.github.io/project-name.
The service is backed by a global content delivery network (CDN), which means your site loads fast for visitors anywhere in the world. GitHub automatically provisions free SSL certificates through Let's Encrypt, so every site gets HTTPS without any configuration. There are no hosting fees, no bandwidth charges (within reasonable limits), and no ads injected into your pages.
| Limit | Value | Notes |
|---|---|---|
| Repository size | 1 GB (soft limit) | Keep images optimized and avoid large binary files |
| Monthly bandwidth | 100 GB | More than enough for most sites; use a CDN for high-traffic assets |
| Builds per hour | 10 | Rarely hit unless deploying every few minutes |
| Site size | 1 GB | Published site output should stay under 1 GB |
| Custom domains | Unlimited | One custom domain per site, but unlimited sites per account |
For most personal projects, portfolios, blogs, documentation sites, and even small business websites, these limits are never reached. GitHub Pages has been trusted by millions of projects including major open-source documentation, developer portfolios, and production websites.
Before deploying to GitHub Pages, you need exactly three things:
index.html file. This can be a simple HTML page, a built React/Vue/Svelte app, or output from any static site generator.git --version. If you see a version number (like git version 2.44.0), you are ready. If not, install Git first.
You have two options for repository naming, and the choice affects your site's URL:
Create a repository named exactly username.github.io (replacing "username" with your actual GitHub username). This becomes your primary site at https://username.github.io. You get one of these per account.
Create a repository with any name (like my-portfolio or my-blog). This deploys to https://username.github.io/repository-name. You can create unlimited project sites.
For most cases, Option B with a custom domain is the way to go. Here is how to create the repository:
Then clone the repository to your local machine:
git clone https://github.com/yourusername/your-repo-name.git cd your-repo-name
At minimum, GitHub Pages needs an index.html file in the root of your repository (or in a /docs folder, depending on your configuration). Here is a minimal example:
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>My Website</title> </head> <body> <h1>Hello, world!</h1> <p>This site is hosted on GitHub Pages for free.</p> </body> </html>
For a real website, you will want to add your CSS files, JavaScript files, images, and any other assets. Organize them however you prefer -- GitHub Pages serves the entire repository structure as-is.
Commit and push your files:
git add . git commit -m "Initial site deployment" git push origin main
This is where the hosting actually turns on. Navigate to your repository on GitHub, then:
https://username.github.io/repository-name.
If you chose GitHub Actions as the source instead of a branch, GitHub will look for a workflow file in .github/workflows/ to build and deploy your site. This is the preferred method for sites using build tools like Jekyll, Hugo, Astro, or any JavaScript framework.
A custom domain transforms username.github.io/project into yourdomain.com. Here is how to set it up:
For an apex domain (example.com), add these A records pointing to GitHub's IP addresses:
185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153
For a subdomain (www.example.com), add a CNAME record:
CNAME www username.github.io
For best results, configure both the apex domain and www subdomain so visitors reach your site regardless of which they type.
example.com)CNAME file in your repository rootCreate a file called CNAME (no extension) in your repository root containing just your domain name:
example.com
Commit this file so it persists across builds and is not accidentally deleted.
After your custom domain's DNS has propagated and GitHub has verified it, HTTPS becomes available:
GitHub provisions a free SSL certificate from Let's Encrypt. This typically takes a few minutes after DNS verification. Once enabled, all HTTP traffic is automatically redirected to HTTPS. There is no certificate to manage, no renewal to remember, and no cost.
If the "Enforce HTTPS" checkbox is grayed out, your DNS has not propagated yet or the certificate is still being provisioned. Wait 15-30 minutes and try again.
For sites that require a build step (JavaScript frameworks, static site generators, preprocessors), GitHub Actions automates the entire build-and-deploy process. Every time you push code, your site rebuilds automatically.
Here is a universal GitHub Actions workflow for deploying to GitHub Pages:
name: Deploy to GitHub Pages
on:
push:
branches: [main]
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
- uses: actions/upload-pages-artifact@v3
with:
path: ./dist
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/deploy-pages@v4
id: deployment
Save this as .github/workflows/deploy.yml in your repository. Adjust the path: ./dist line to match your build output directory (build for Create React App, out for Next.js static export, public for Hugo, etc.).
Static site generators transform templates and content into fast, pre-built HTML. Here are the most popular options and how they work with GitHub Pages:
Jekyll is the only static site generator with native GitHub Pages support. Push your Jekyll source files and GitHub builds the site automatically -- no Actions workflow needed. Add a _config.yml file to configure your site, create posts in _posts/ using Markdown, and GitHub handles the rest.
Hugo is the fastest static site generator, building thousands of pages in milliseconds. Use a GitHub Actions workflow with peaceiris/actions-hugo to build and deploy. Hugo is ideal for large blogs and documentation sites.
Astro is the modern choice for content-focused websites. It ships zero JavaScript by default and supports React, Vue, Svelte, and Solid components. Use withastro/action in your GitHub Actions workflow for seamless deployment.
Next.js can export a fully static site with output: 'export' in next.config.js. This removes all server-side features but produces a fast static site perfect for GitHub Pages. The standard Node.js GitHub Actions workflow handles the build.
No generator needed. Just push your HTML files directly. This is the simplest approach and works perfectly for portfolios, landing pages, and web apps built with vanilla JavaScript or bundled with Vite, Parcel, or webpack.
index.html exists in the root of your selected branch/folderusername.github.io./styles.css) instead of absolute paths (/styles.css) for project sites/repo-name/styles.css<base> tag can fix path issues: <base href="/repo-name/">dig example.com +short -- should show GitHub's IP addressesGemfile uses github-pages gem for compatibilitynpm run build works locally before pushingdefer or async attributessitemap.xml to help search engines discover all pagesrobots.txt allowing full crawling<title> tags and <meta name="description"> on every pageYou can run an entire network of websites from a single GitHub account for free. Each repository gets its own GitHub Pages site, and each can have its own custom domain. This is exactly how the Spunk Network operates -- spunk.codes, spunk.bet, spunk.work, spunk.pics, and spunkart.com all run on GitHub Pages with custom domains.
Create a 404.html file in your repository root. GitHub Pages serves this automatically for any URL that does not match an existing file. Use this to redirect users back to your homepage or show a helpful error page.
Never commit API keys, passwords, or secrets to your repository. For GitHub Actions workflows that need secrets (API tokens, deploy keys), use Settings → Secrets and variables → Actions to store them securely. Reference them in workflows with ${{ secrets.SECRET_NAME }}.
spunk.codes has 250+ free tools -- all built with HTML, CSS, JavaScript, and deployed on GitHub Pages.
Explore spunk.codes →Yes, GitHub Pages is completely free for public repositories. You get free hosting, free HTTPS via Let's Encrypt, free custom domain support, and a global CDN. There are soft limits of 1 GB repository size, 100 GB monthly bandwidth, and 10 builds per hour, but these are more than enough for most websites. Private repositories on free GitHub accounts can also use GitHub Pages.
Yes. GitHub Pages supports custom domains including apex domains (example.com) and subdomains (www.example.com). You configure DNS records at your domain registrar pointing to GitHub's servers, then add the custom domain in your repository settings. GitHub automatically provisions a free HTTPS certificate via Let's Encrypt for your custom domain.
GitHub Pages hosts static websites only. This includes HTML, CSS, JavaScript, images, and any client-side code. You can use static site generators like Jekyll, Hugo, Astro, Next.js (static export), and Gatsby. You cannot run server-side code (PHP, Python, Node.js backends, databases). For dynamic features, use client-side JavaScript with external APIs.
The most common causes of 404 errors are: wrong branch selected in repository settings (should be main or gh-pages), missing index.html in the root or docs folder, incorrect repository name for user sites (must be username.github.io), or the site has not finished building yet (wait 2-5 minutes). Check the Actions tab for build errors and ensure your source branch and folder are correctly configured.
Absolutely. GitHub Pages is one of the best platforms for blogs and portfolios. Jekyll is built in and requires zero configuration. For modern frameworks, use GitHub Actions to build and deploy automatically on every push. Thousands of developer portfolios, project documentation sites, and blogs run on GitHub Pages with zero hosting costs.
Part of the SpunkArt Network