GitHub Pages is static website hosting built into GitHub. It works well for portfolios, project documentation, and blogs: GitHub publishes files such as HTML, CSS, JavaScript, and images to a website. It is not a general-purpose application server, and its limits affect what you can build and how you can use it.
Technical and architectural limits
- Static files only: Pages serves static assets. It does not run server-side application code such as PHP, Node.js, Python, or Ruby, and it does not provide database connections such as MySQL or MongoDB. A dynamic application needs a separate backend or hosting platform.
- Repository visibility: On GitHub Free, publishing from a private repository has plan and repository-type restrictions. If your Pages site must use a public repository, assume its source can be read, copied, and downloaded by anyone. Check GitHub’s current Pages plan requirements before choosing repository visibility.
- Do not handle secrets or sensitive transactions in the browser: Static client-side code cannot keep credentials or API keys secret. Do not collect or process passwords, payment-card information, or other sensitive data directly in a Pages site; use a properly secured backend and an appropriate payment provider.
Usage and storage thresholds
- Site size: A published Pages site must be no larger than 1 GB. Keep large media files on a service designed to deliver them rather than checking them into the site.
- Bandwidth: GitHub documents a soft bandwidth limit of 100 GB per month. A media-heavy site or a sudden increase in traffic can reach this threshold.
- Builds and deployments: GitHub documents a soft limit of 10 builds per hour and a 10-minute deployment timeout. Frequent builds or very large sites may run into these constraints.
These are published thresholds, not a substitute for checking GitHub’s current documentation. Limits and enforcement details can change.
Business and site-count considerations
- Commercial use: GitHub Pages is not intended to serve as free hosting for an online business, e-commerce site, or commercial SaaS product. Review GitHub’s terms and current Pages policies before using it for a commercial project.
- User and project sites: An account can have one user or organization site, typically at
username.github.io. Project sites are published from repositories under a different URL path, but do not assume they are unlimited—review current account and Pages limits when planning multiple sites.
Good fit: A portfolio, blog, or documentation site made of public static files. Choose another architecture when you need private server-side logic, a database, user accounts, secure transactions, or a commercial storefront.
Before you commit to GitHub Pages, ask what the site needs to do: Does it need a backend or persistent user data? Will the source code need to remain private? Is it intended to support commercial transactions? If any answer is yes, plan for a separate application backend or a hosting service designed for that workload.
For current requirements and thresholds, check the GitHub Pages documentation and GitHub’s Pages limits.