GitHub Pages: What It Hosts, Its Limits, and When It Fits

GitHub Pages hosts static sites only — HTML, CSS, and JavaScript files taken straight from a repository — and it's free, but GitHub's own usage policy says it isn't for running a commercial or e-commerce site. GitHub describes it plainly: "GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website" (GitHub Docs, "About GitHub Pages", checked September 2026). This covers what that actually means: publishing sources, the Jekyll default, the documented limits, and who GitHub says it isn't for.

What does GitHub Pages actually host?

Static files, full stop. GitHub's own setup guide is direct about the boundary: "GitHub Pages does not support server-side languages such as PHP, Ruby, or Python" (GitHub Docs, "Creating a GitHub Pages site", checked September 2026). There's no server-side runtime behind a Pages site — no database connection, no PHP include, no Python backend. If your project needs one of those, GitHub Pages isn't the host; a plain HTML/CSS/JS export, or a static site generator's build output, is exactly what it's built for.

That entry file matters too: "GitHub Pages will look for an index.html, index.md, or README.md file as the entry file for your site" (same source). Without one of those at the right level of your publishing source, there's no homepage to serve.

How do I publish a GitHub Pages site?

You pick a publishing source in your repository's Settings → Pages, and GitHub gives you two real options.

Deploy from a branch. Choose a branch, then choose either the repository root or a /docs folder as the source. GitHub's documentation says: "Whenever changes are pushed to the source branch, the changes in the source folder will be published to your GitHub Pages site" (GitHub Docs, "Configuring a publishing source for your GitHub Pages site", checked September 2026). Push to that branch, and the live site updates on its own.

Deploy with GitHub Actions. You pick a starter workflow or write your own, and GitHub builds and deploys the site through a normal Actions run — checking out the repository, building the static output if needed, then uploading and deploying it with GitHub's own Pages actions (same source). GitHub currently steers people toward this option: "GitHub Actions is now the recommended approach for deploying and automating GitHub Pages sites" (GitHub Docs, "About Jekyll build errors for GitHub Pages sites", checked September 2026), while noting the older Jekyll-based build process is still supported for sites that use it.

Either way, a change doesn't appear instantly. GitHub's docs note: "It can take up to 10 minutes for changes to your site to publish after you push the changes to GitHub" (same source).

Does GitHub Pages use Jekyll by default?

Yes, if you're publishing from a branch. GitHub's own documentation is direct about this: "If you publish your site from a source branch, GitHub Pages will use Jekyll to build your site by default" (GitHub Docs, "Creating a GitHub Pages site", checked September 2026). Jekyll is a static site generator with built-in GitHub Pages support, and GitHub's Jekyll documentation says plainly: "We recommend using Jekyll with GitHub Pages" (GitHub Docs, "About GitHub Pages and Jekyll", checked September 2026).

You aren't locked into it. The same page notes: "If you prefer, you can use other static site generators or customize your own build process locally or on another server." If your source is plain, already-built HTML and you don't want Jekyll's processing (which treats files and folders starting with an underscore as special and skips them), you have two outs: publish through a GitHub Actions workflow instead of a branch, which sidesteps the Jekyll step entirely, or add a .nojekyll file to bypass it on a branch-based site.

What are GitHub Pages' size, bandwidth, and build limits?

GitHub documents these directly, and calls two of them "soft" limits rather than hard cutoffs (GitHub Docs, "GitHub Pages limits", checked September 2026):

"Soft" is GitHub's own word for the bandwidth and build-frequency numbers, not ours — it's reasonable to read that as headroom rather than a promise the site goes down the instant you cross it, but GitHub doesn't spell out what happens if you exceed it, so don't plan a high-traffic launch around that ambiguity.

What can't I use GitHub Pages for?

GitHub's usage policy names this directly, and it's worth quoting in full because it's more specific than "no commercial use": "GitHub Pages is not intended for or allowed to be used as a free web-hosting service to run your online business, e-commerce site, or any other website that is primarily directed at either facilitating commercial transactions or providing commercial software as a service (SaaS)" (GitHub Docs, "GitHub Pages limits", checked September 2026).

Read narrowly, that's aimed at sites whose whole purpose is a business's commercial transactions or a SaaS product — not, say, a freelancer's portfolio that happens to have a "hire me" link. But if what you're building is a storefront, a booking system, or a hosted SaaS product's marketing-plus-app site, GitHub Pages' own policy says that's not what it's for, regardless of the technical limits above.

Can I use GitHub Pages with a private repository?

It depends on your plan, and the private repository and a private site are two different things. GitHub's plan documentation states that GitHub Free (personal accounts) includes "GitHub Pages in public repositories" — meaning the free personal tier requires your Pages source to be a public repo (GitHub Docs, "GitHub's products", checked September 2026). GitHub Pro and GitHub Team both list GitHub Pages without that public-only restriction, so a private repository can be a Pages source on those plans.

But the published site itself is still public either way, unless you take a further step. GitHub Pages works from private repositories on GitHub Pro, Team and Enterprise plans (GitHub Docs, "About GitHub Pages"), but a private repository does not make the site private. To make the site itself private — visible only to people with repository access — GitHub's documentation is specific: "To publish a GitHub Pages site privately, you need to have an organization account. Additionally, your organization must use GitHub Enterprise Cloud" (GitHub Docs, "GitHub's plans"). A personal Pro account, in other words, can source Pages from a private repo, but can't make the resulting site private; only an organization on GitHub Enterprise Cloud can do that.

What about a custom domain?

GitHub Pages supports one, with a fully documented DNS and verification process — specific A and AAAA records for an apex domain, a CNAME for www, a repository-side CNAME file, and a recommended domain-verification step. Our guide to using a custom domain with GitHub Pages walks through that setup exactly as GitHub documents it, so this guide won't repeat it here.

Is GitHub Pages the right fit for my site?

It's a strong fit for a static site you're comfortable keeping in a Git repository: documentation, a portfolio, a project's marketing page, a blog built with a static generator. It's a poor fit the moment you need server-side logic GitHub Pages doesn't run, or the site's actual purpose is a commercial transaction or a hosted SaaS product, which GitHub's own usage policy excludes.

If you're arriving at GitHub Pages with a folder of already-built, reviewed HTML and CSS rather than a Git-based workflow, our checklist for publishing an AI-generated static site covers the review and rollback steps that apply regardless of which static host you pick. And if your site's source of truth is a Figma design rather than a codebase you want to maintain in Git, that's a different starting point entirely — Figment publishes a Figma file directly, with no repository or build step involved.

Bottom line: GitHub Pages is free, fully documented static hosting with real, stated limits — 1 GB per published site, a soft 100 GB/month bandwidth allowance, Jekyll by default from a branch (with an escape hatch), and a usage policy that rules out commercial and e-commerce sites. Read the limits and the usage policy before you commit a business site to it; for a personal project, a docs site, or a static export, it's exactly what it says it is.