Published February 27, 2026 · 18 min read
GitHub Pages is one of the best-kept secrets in web hosting. It provides free, reliable hosting for static websites directly from a GitHub repository. No server to manage, no hosting bill, no complicated setup. Push your code to GitHub and your website is live within minutes.
We use GitHub Pages to host spunk.codes, spunk.bet, and dozens of other sites in our network. It handles millions of page views, serves over HTTPS, supports custom domains, and costs exactly zero dollars. This guide covers everything you need to know to do the same.
Getting a website live on GitHub Pages takes less than five minutes. Here is the process from start to finish.
Create a new repository on GitHub. For a user site (yourusername.github.io), name the repository exactly yourusername.github.io. For a project site, use any name you want. The repository can be public (free for all users) or private (free for GitHub Pro, Teams, or Enterprise).
Push your HTML, CSS, JavaScript, and image files to the repository. At minimum, you need an index.html file in the root directory. This becomes your homepage. You can use any folder structure you want for additional pages.
Go to your repository's Settings tab, scroll to the Pages section, and select the source branch (usually main) and folder (root or /docs). Click Save. Within a minute or two, your site is live at https://yourusername.github.io (for user sites) or https://yourusername.github.io/repo-name (for project sites).
Navigate to the URL in your browser. If you see your website, the setup is complete. If you see a 404 error, check that your index.html is in the correct directory (root or /docs depending on your Pages configuration) and that the correct branch is selected.
GitHub Pages supports custom domains at no extra cost. You can use an apex domain (example.com), a subdomain (www.example.com), or both. Here is how to set it up.
Create a file named CNAME (no extension) in the root of your repository. The file should contain only your custom domain, for example: example.com. Commit and push this file.
At your domain registrar or DNS provider, add the following records.
| Record Type | Name | Value | Purpose |
|---|---|---|---|
| A | @ | 185.199.108.153 | Apex domain to GitHub Pages |
| A | @ | 185.199.109.153 | Apex domain to GitHub Pages |
| A | @ | 185.199.110.153 | Apex domain to GitHub Pages |
| A | @ | 185.199.111.153 | Apex domain to GitHub Pages |
| CNAME | www | yourusername.github.io | www subdomain redirect |
Go to Settings → Pages and enter your custom domain. GitHub will run a DNS check. Once verified, check the "Enforce HTTPS" box. DNS propagation can take up to 48 hours, but usually completes within 30 minutes.
GitHub Pages provides free HTTPS via Let's Encrypt certificates. This is automatic for the default github.io domain and available for custom domains once DNS is properly configured.
If the "Enforce HTTPS" checkbox is grayed out, your DNS is not fully propagated or the CNAME file does not match your domain exactly. Wait a few hours and try again. If it still fails, remove the custom domain in GitHub settings, save, re-add it, and save again. This forces GitHub to re-provision the certificate.
GitHub Pages has built-in Jekyll support. Jekyll is a static site generator that converts Markdown files into HTML pages. When you push Markdown files to a Jekyll-enabled repository, GitHub builds the HTML automatically.
You are not limited to Jekyll. GitHub Pages can host output from any static site generator. The difference is that non-Jekyll generators require a build step via GitHub Actions.
| Generator | Language | Speed | Best For |
|---|---|---|---|
| Jekyll | Ruby | Moderate | Blogs, documentation (built-in GitHub support) |
| Hugo | Go | Very fast | Large sites, fast builds (1000+ pages in seconds) |
| Astro | JavaScript | Fast | Modern web apps, partial hydration |
| Next.js (static export) | JavaScript | Moderate | React apps with static export |
| Eleventy (11ty) | JavaScript | Fast | Flexibility, multiple template languages |
| Plain HTML | N/A | Instant | Simple sites, full control, no build step |
At SPUNK.CODES, we use plain HTML files without any static site generator. Every page is a single self-contained HTML file with inline CSS. This means zero build time, zero dependencies, instant deployments, and complete control over every byte of output. For sites with fewer than 500 pages, plain HTML is often faster and simpler than any generator.
GitHub Actions allows you to automate builds and deployments for non-Jekyll static site generators. When you push code, an Action runs your build command and deploys the output to GitHub Pages.
Create a file at .github/workflows/deploy.yml in your repository. This workflow installs Hugo, builds your site, and deploys the output to GitHub Pages on every push to the main branch.
name: Deploy to GitHub Pages
on:
push:
branches: [main]
jobs:
build-deploy:
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
steps:
- uses: actions/checkout@v4
- name: Setup Hugo
uses: peaceiris/actions-hugo@v3
with:
hugo-version: 'latest'
- name: Build
run: hugo --minify
- name: Deploy
uses: actions/deploy-pages@v4
GitHub Pages is powerful but has specific limitations you need to understand before building on it.
| Limitation | Details | Workaround |
|---|---|---|
| Static files only | No server-side code (PHP, Python, Node.js) | Use serverless functions (Cloudflare Workers, Vercel Edge) |
| Repository size | Recommended under 1 GB | Use Git LFS for large assets or external CDN |
| Site size | Published sites should be under 1 GB | Optimize images, use external hosting for media |
| Bandwidth | 100 GB/month soft limit | Use a CDN (Cloudflare free tier) for high-traffic sites |
| Build frequency | 10 builds per hour limit | Batch commits, use GitHub Actions with caching |
| No .htaccess | Cannot configure server-level redirects | Use JavaScript redirects or 404.html for SPA routing |
| No forms processing | No server to handle form submissions | Use Formspree, Netlify Forms, or Google Forms |
For production sites, put Cloudflare (free tier) in front of your GitHub Pages site. Cloudflare provides a CDN cache (faster page loads globally), DDoS protection, analytics, and page rules for redirects. This combination of GitHub Pages + Cloudflare gives you enterprise-grade hosting for free.
GitHub Pages serves a file named 404.html in your repository root for any URL that does not match a file. Use this for custom error pages or for single-page application (SPA) routing. For SPAs, the 404.html can redirect all requests to your index.html with a URL hash that the JavaScript router processes.
Every image you push to the repository counts toward the 1 GB recommendation. Compress images with tools like Squoosh, TinyPNG, or ImageOptim before committing. Use WebP format for the best size-to-quality ratio. A typical blog post image should be under 100 KB.
Each GitHub repository can have its own GitHub Pages site. If you manage multiple websites (like our network of 100+ sites), each one gets its own repository, its own custom domain, and its own deployment pipeline. There is no limit on the number of GitHub Pages sites per account.
When you update CSS or JavaScript files, browsers may serve cached versions. Append a version query string to your file references: style.css?v=2. Update the version number with each change. This forces browsers to download the latest file while still allowing caching between updates.
Set up a GitHub Action that runs periodically (cron schedule) to check if your site is online and responding correctly. If a deployment breaks your site, you will get notified immediately instead of discovering it hours or days later.
Use our free Landing Page Builder to create a professional, responsive landing page ready for GitHub Pages deployment.
Get the Free Landing Page BuilderGitHub Pages is genuinely free for public repositories with no hidden costs. For private repositories, you need GitHub Pro ($4/month) or a GitHub Teams/Enterprise plan. The "catch" is that it only hosts static files. You cannot run server-side code, databases, or server processes. For static websites, blogs, documentation sites, portfolios, and landing pages, there is no catch at all. GitHub has offered Pages as a free service since 2008 and it remains one of the most reliable free hosting options available.
Yes, with a caveat. GitHub's soft bandwidth limit is 100 GB per month. For a typical web page that is 500 KB including all assets, that is roughly 200,000 page views per month before you approach the limit. For higher traffic, put Cloudflare's free CDN in front of your site. Cloudflare caches your pages at edge locations worldwide and serves most requests without hitting GitHub at all. With Cloudflare, GitHub Pages sites can handle millions of monthly page views without issues. We do this for all of our production sites.
You can build the front-end of an e-commerce site on GitHub Pages, but payment processing and order management require server-side functionality. The most common approach is a static front-end on GitHub Pages combined with Stripe Checkout (hosted payment pages), Snipcart (JavaScript shopping cart), or Shopify's Buy Button (embedded product widgets). These services handle the server-side payment and order logic while your static site handles product display and the shopping experience.