GitHub Pages limits: check whether your website still fits
Check GitHub Pages site size, bandwidth, deployment limits, public visibility, and permitted use before keeping your site there or choosing another host.
In this guide
GitHub Pages can be a good home for a personal site or project documentation. Before moving because you have seen a limit, check what your site does, what gets published, and which limit you are actually approaching. A small documentation site does not need a new host just because a paid plan exists.
If you want to run a shop, a commercial software service, or a server-side Python app, size is not the first question. GitHub Pages has both usage restrictions and a static-hosting boundary. This guide helps you decide whether to keep it, fix a specific problem, or choose different hosting.
Check the type of site first
GitHub Pages serves static files: ready-made HTML, CSS, and JavaScript. A build can generate those files, but that does not leave Python, PHP, or a database running to answer visitors’ requests. Browser JavaScript can still work; a WordPress installation cannot run on Pages itself.
GitHub’s usage policy rules out using Pages as free hosting to run an online business, an e-commerce site, or a site primarily facilitating commercial transactions or commercial SaaS. It also says not to use Pages for sensitive transactions such as passwords or card details.
Do not assume that a small shop becomes eligible by putting checkout elsewhere. If a project’s business use is unclear, resolve that with GitHub before relying on it. Paying for GitHub Pro does not by itself waive the Pages usage policy.
The limits that affect a small site
These figures were checked in GitHub’s official documentation on October 2, 2026. A soft limit is a usage boundary that may lead to restrictions or a request to reduce use; it is not a promise of a particular overage price.
| Limit | Published boundary | What to inspect |
|---|---|---|
| Published site | Maximum 1 GB | The generated files you actually publish, including images and downloads. |
| Source repository | Recommended 1 GB limit | Source files and repository history, which differ from the published output. |
| Bandwidth | Soft limit of 100 GB per month | Large downloads and heavy assets, not only page count. |
| Deployment | Times out after 10 minutes | The failed deployment's log and slow steps. |
| Build frequency | Soft limit of 10 builds per hour | Whether repeated updates are triggering unnecessary builds. |
The ten-builds-per-hour limit does not apply when a custom GitHub Actions workflow builds and publishes the site. That exception does not remove the other Pages limits or GitHub Actions’ own usage terms.
Check your own site without guessing from visitor counts
For an Astro static project, build it and inspect the output folder, normally dist. For another generator, identify its actual publishing folder first. In your file manager, open that folder’s Properties or Get Info and check its total file size, rather than the size of the whole project or the disk space allocated to it.
Look for oversized images, bundled archives, and videos. Removing an accidental source export from the output is more useful than moving the entire site to accommodate it. Keep a local backup, fix the build’s inputs, and verify the generated site before publishing a correction.
Bandwidth is the data delivered over time, not the space occupied by the site. For illustration, a 5 MB download fetched 1,000 times transfers about 5 GB using decimal units, before counting page assets. This is a rough calculation, not a measurement: caching, repeat visits, bots, and which files people request all change the total. An analytics visitor count alone cannot prove bandwidth use.
If deployment fails, inspect the latest run’s log in your repository’s Actions tab. Find the first failed step. A broken build command, a missing file, and a deployment timeout need different fixes; buying hosting before reading the error may leave the original problem untouched.
A private repository is not a private website
On GitHub Free, Pages requires a public source repository. Some paid plans allow publishing from private repositories. However, GitHub’s site creation guide warns that Pages sites are publicly available even when their source repository is private, unless you have a supported access-controlled publishing setup.
Treat every file in the published output as public. Keep credentials, customer exports, and unpublished client material out of it. If your requirement is a private client portal, choose and verify real access control rather than relying on an obscure URL or the repository’s privacy setting.
Stay, fix, or move?
- Stay if your personal or documentation site fits the policy, is intended to be public, and has no relevant limit problem.
- Fix the narrow problem if a few large files or an unnecessary build loop are responsible. Recheck after the fix instead of assuming a migration is necessary.
- Compare static hosts if the site still consists of public files but needs different hosting features or usage terms. Cloudflare Pages vs Netlify gives a small-site decision path without assuming a paid upgrade.
- Choose an appropriate application host if visitors need server-side processing or accounts. Start by identifying that requirement; static vs dynamic websites can help separate it from ordinary browser interactivity.
The next useful step is to name one concrete blocker: policy, public visibility, output size, deployment, or a missing runtime. If none applies, you may already have the hosting you need.
Sources and useful links
- GitHub Pages limits — authoritative usage restrictions, quotas, and the custom-workflow exception.
- What GitHub Pages is — static hosting, site types, and supported repository plans.
- Create a GitHub Pages site — publishing sources, visibility warnings, and where to find the deployed site.