You already have the code. You already have the repository. So why pay for hosting?
GitHub Pages is a free static site hosting service built directly into GitHub. It turns any repository into a live, publicly accessible website with zero infrastructure setup.
Developers use it for portfolios, open source documentation, and project sites. It supports plain HTML, CSS, JavaScript, Jekyll, and custom build pipelines via GitHub Actions.
This article covers what GitHub Pages is, how the static site deployment process works, what types of sites it supports, its limits, pricing, and how to set one up from scratch.
What Is GitHub Pages?
GitHub Pages is a free static site hosting service built directly into GitHub. It publishes a website from a GitHub repository automatically every time you push changes.
No separate hosting account. No FTP uploads. No server to configure. The repository is the deployment pipeline.
GitHub Pages supports HTML, CSS, JavaScript, and Jekyll-based static sites out of the box. It assigns every published site a default URL in the format username.github.io, with optional custom domain support. GitHub, owned by Microsoft, launched the service to let developers publish project documentation, portfolios, and open source sites without leaving their existing workflow.
WebTechSurvey data shows over 58 million live websites currently use GitHub Pages (WebTechSurvey, 2025).
If you already work with GitHub daily, adding a published website takes minutes. That zero-friction setup is the main reason it became the default choice for open source documentation and developer portfolios.
How Does GitHub Pages Work?
GitHub Pages reads static files from a designated source in your repository and serves them as a live website. Push a change, and the site updates automatically. No manual deployment step required.
Understanding the build and deployment flow helps explain why some setups work instantly while others need extra configuration.
How GitHub Pages Builds and Deploys a Site
Two deployment methods exist:
- Deploy from a branch (main, master, or gh-pages)
- Deploy via a custom continuous deployment workflow using GitHub Actions
When deploying from a branch, GitHub Pages runs a Jekyll build automatically on every push to the source branch. Plain HTML, CSS, and JavaScript files skip the Jekyll processing step and get served exactly as-is.
GitHub Actions is now the recommended approach for anything beyond basic Jekyll sites. It gives you full control over the build pipeline, so React, Hugo, Eleventy, and other frameworks all work without workarounds.
What Is the gh-pages Branch?
The gh-pages branch is a dedicated Git branch GitHub Pages recognizes as a publishing source for project sites.
Many tools (including older versions of Create React App) automatically push built output to this branch. It keeps generated static files separate from your main development codebase.
You are not required to use it. GitHub Pages also reads from the root of the main branch or a /docs folder. The gh-pages branch is just the most common convention for project sites.
What Types of GitHub Pages Sites Are There?
GitHub Pages creates 3 distinct site types: user sites, organization sites, and project sites. Each has different naming rules, URL structures, and source branch behavior.
| Site Type | Who Creates It | Published URL | Limit |
|---|---|---|---|
| User site | Individual GitHub account | username.github.io | 1 per account |
| Organization site | GitHub organization | orgname.github.io | 1 per organization |
| Project site | Any repository | username.github.io/repo-name | Unlimited |
User and organization sites require a repository named exactly username.github.io or orgname.github.io. The naming convention is what triggers the correct site type. Get the name wrong and GitHub treats it as a project site instead.
Project sites are the most common. Every repository you own can have one, published at a subpath under your main github.io domain.
What Does GitHub Pages Support?
GitHub Pages natively supports Jekyll, plain static files, and GitHub Actions-driven custom builds. The combination covers most use cases without needing a third-party hosting account.
Jekyll and Markdown Support
Jekyll is the default build engine. GitHub runs it server-side automatically when it detects a Jekyll project in the source branch.
Jekyll converts Markdown files and Liquid templates into complete HTML pages. Sites like Ruby on Rails documentation and Spotify for Developers run on Jekyll hosted via GitHub Pages (Kinsta, 2025).
Key built-in Jekyll capabilities:
- Markdown-to-HTML conversion using kramdown
- Liquid templating language for dynamic layouts
- Built-in themes configurable via config.yml
- Syntax highlighting through Rouge
Custom Builds with GitHub Actions
GitHub Actions is now the recommended build method for non-Jekyll frameworks (GitHub Docs, 2025).
React, Vue, Next.js (static export), Hugo, and Eleventy all work through a custom Actions workflow. The workflow builds the framework output, then pushes the resulting static files to the Pages deployment environment.
GitHub provides official workflow templates for the most common static site generators, which cuts setup time significantly.
Custom Domain and HTTPS
Every GitHub Pages site gets HTTPS automatically via Let’s Encrypt. No manual certificate setup needed.
Custom domains work through a CNAME file or the Settings > Pages panel. Apex domains require 4 A records pointing to GitHub’s IP addresses. Subdomains use a single CNAME record pointing to username.github.io.
What Are the Limits of GitHub Pages?
GitHub Pages has 4 hard technical limits that matter in practice: repository size, published site size, monthly bandwidth, and build frequency (GitHub Docs, 2025).
| Limit Type | Value | Hard or Soft |
|---|---|---|
| Repository size | 1 GB recommended | Soft |
| Published site size | 1 GB | Soft |
| Monthly bandwidth | 100 GB | Soft |
| Builds per hour | 10 (branch-based only) | Soft |
“Soft” means GitHub may suspend or throttle the site rather than block it outright. Sites that consistently exceed 100 GB/month will receive a notice from GitHub Support suggesting alternatives.
The 10 builds-per-hour cap does not apply to custom GitHub Actions workflows. That limit only affects the automatic Jekyll build triggered by branch pushes.
What GitHub Pages cannot do: run server-side code, connect to a database, or execute PHP, Node.js, or Python at request time. It serves static files only. For dynamic features, developers typically use client-side JavaScript with third-party APIs or serverless functions hosted elsewhere.
Who Uses GitHub Pages?
GitHub Pages is used by individual developers, open source projects, and engineering teams that need reliable static hosting without infrastructure overhead.
As of early 2025, GitHub has over 150 million developers worldwide (ElectroIQ, 2025). A significant portion of those developers host at least one GitHub Pages site for documentation or a portfolio.
Developer Portfolios and Personal Sites
Portfolio hosting is the most common personal use case. GitHub hosts over 27,000 public portfolio-website repositories, the majority deployed via GitHub Pages (GitHub Topics, 2025).
The appeal is straightforward:
- No hosting cost for public repositories
- Version-controlled updates through standard Git workflow
- Custom domain support included at no cost
For front-end development work especially, a GitHub Pages portfolio doubles as a live demo and a code sample in one URL.
Open Source Project Documentation
Bootstrap, Jekyll itself, Ruby on Rails, and Spotify for Developers all host their documentation on GitHub Pages (Kinsta, 2025).
Open source projects use it because the documentation lives in the same repository as the code. Contributors can submit documentation fixes through pull requests using the same workflow they use for code changes. The technical documentation stays in sync with the codebase without a separate CMS.
Academic and Educational Publishing
Universities and researchers use GitHub Pages to publish course materials, academic portfolios, and research project sites. Jekyll’s Markdown support makes it practical for non-developers who know basic text formatting but not HTML.
Hugo Academic (now Wowchemy) is a popular theme built specifically for this use case, with citation support and publication listings built in.
How Does GitHub Pages Handle Custom Domains?
GitHub Pages supports custom domains through DNS configuration and a CNAME file or Settings panel entry. HTTPS is provisioned automatically via Let’s Encrypt after DNS propagates, with no manual certificate management.
Apex Domain vs. Subdomain Setup
Apex domain (example.com): Requires 4 A records pointing to GitHub’s IP addresses:
- 185.199.108.153
- 185.199.109.153
- 185.199.110.153
- 185.199.111.153
Subdomain (www.example.com): Requires a single CNAME record pointing to username.github.io.
After DNS propagation (typically 24-48 hours), GitHub auto-provisions the Let’s Encrypt certificate. The github.io subdomain remains active alongside the custom domain unless the CNAME record fully replaces it.
Domain Verification
GitHub added verified custom domain support to prevent domain takeover attacks. Verifying a domain at the profile or organization level ensures that only repositories under your account can publish to that domain.
Domain verification requires adding a DNS TXT record with a GitHub-generated code. It takes under 5 minutes to set up and is strongly recommended for any domain you plan to keep long-term.
How Does GitHub Pages Compare to Other Static Hosting Platforms?
GitHub Pages is a static file publisher attached to a repository. Netlify and Vercel are full deployment platforms that also handle builds, previews, serverless functions, and environment configuration (Startupik, 2026).
The right choice depends on what you are deploying and how complex your workflow needs to be.
| Platform | Best For | Serverless Functions | Free Tier |
|---|---|---|---|
| GitHub Pages | Docs, portfolios, open-source sites | No | Public repositories only |
| Netlify | JAMstack apps, landing pages, content sites | Yes (AWS Lambda) | Yes, with build-minute limits |
| Vercel | Next.js apps, React SPAs, edge rendering | Yes (Edge Functions) | Yes, for non-commercial usage |
| Cloudflare Pages | High-traffic static sites with edge compute | Yes (Cloudflare Workers) | Yes, with generous limits |
GitHub Pages vs Netlify
Netlify pioneered the continuous integration to deploy workflow that GitHub Actions later replicated for Pages. Today Netlify goes well beyond static hosting.
Netlify adds: built-in form handling, deploy previews per pull request, identity and authentication options, and redirect rules configurable without server access.
GitHub Pages has none of those features natively. For a developer portfolio or open source docs site, that’s fine. For a marketing site that needs A/B testing or lead-capture forms, Netlify is the better fit.
GitHub Pages vs Vercel
Vercel was built by the team behind Next.js. That alignment affects image optimization, middleware, server components, and caching behavior in ways GitHub Pages cannot replicate (CraftedTemplate, 2025).
GitHub Pages requires Next.js to export fully static output. Vercel supports incremental static regeneration and server-side rendering out of the box.
Vercel also requires all commercial use to be on a paid plan. GitHub Pages has no such restriction for public repositories.
GitHub Pages vs Cloudflare Pages
Cloudflare Pages runs on the same global edge network used by Cloudflare’s enterprise customers. For static content delivery, it typically outperforms GitHub Pages on time-to-first-byte across international locations.
Key difference: Cloudflare Pages combined with Workers becomes a full-stack edge platform. GitHub Pages stays purely static. For teams that want to add API routes later without switching hosts, Cloudflare Pages has more headroom.
Is GitHub Pages Free?
GitHub Pages is free for all public repositories on every plan tier, including GitHub Free. Custom domain support, HTTPS via Let’s Encrypt, and the full static hosting feature set are included at no cost (GitHub Docs, 2025).
Private repository publishing is a different story.
What the Free Plan Includes
Free plan users get:
- Unlimited public repository hosting
- Custom domain support with verified domain protection
- Auto-provisioned HTTPS certificate
- 100 GB soft bandwidth per month
- GitHub Actions minutes for builds (free for public repos)
One catch worth knowing: even if your source repository is private, the published website is always public. Anyone with the URL can access it (GitHub Blog, 2025).
When You Need a Paid Plan
Private repository Pages publishing requires GitHub Enterprise Cloud for organizations. Individual Pro and Team accounts can publish from private repos, but full private Pages with organization-level control needs Enterprise Cloud (GitHub Docs, 2025).
GitHub Actions minutes used by custom build workflows count against your account’s included minutes for private repos. Public repos run Actions for free with no minute cap.
For most developers hosting a portfolio or open source documentation, the free tier covers everything. The paid requirement only becomes relevant for teams that need private source code combined with a publicly accessible site.
How Do You Set Up GitHub Pages?
A basic GitHub Pages site goes live in under 5 minutes. The setup requires a GitHub repository, an index.html file, and 3 clicks in the Settings panel.
GitHub Actions adds a few more steps but gives you full control over the app deployment process for any framework.
Basic Setup from a Branch
5 steps to publish a static site:
- Create or open a GitHub repository
- Add an index.html file to the repository root and push it
- Go to Settings > Pages in the repository
- Under “Build and deployment,” select “Deploy from a branch” and choose main (or master)
- Save. The site publishes at username.github.io/repo-name within minutes
The site URL appears at the top of Settings > Pages once the first build completes. GitHub also adds an “Environments” section to the repository sidebar showing deployment status.
How to Enable Jekyll on GitHub Pages
Jekyll activates automatically when GitHub detects a config.yml file in the repository root. No separate installation or build command needed for branch-based deployments.
Minimum Jekyll setup:
- Add config.yml with at least a title field
- Write content in .md Markdown files
- Choose a theme by adding
theme: minima(or any supported theme) to config.yml
Jekyll is not officially supported on Windows locally, but the GitHub-side build runs on Linux regardless of your development environment.
How to Use GitHub Actions for Custom Builds on GitHub Pages
GitHub Actions replaces the automatic Jekyll build with a custom workflow. This is how React, Vue, Hugo, Eleventy, and Next.js static exports get deployed to Pages.
Setup order matters here. Enable GitHub Pages and set the source to “GitHub Actions” in Settings before pushing the workflow file. Pushing the workflow first causes it to fail because the github-pages deployment environment does not exist yet (DEV Community, 2025).
GitHub provides official starter workflows for the most common build automation setups. Look under Actions > New Workflow > Pages to find templates for Jekyll, Hugo, Next.js, Nuxt, and Gatsby.
Once configured, every push to the main branch triggers the workflow, builds the static output, and deploys it automatically. The deployment pipeline runs end-to-end without any manual steps after the initial configuration.
More on the full publishing workflow and domain verification is covered in our guide on how to deploy to GitHub Pages.
FAQ on GitHub Pages
What is GitHub Pages used for?
GitHub Pages hosts static websites directly from a GitHub repository. Developers use it for personal portfolios, project documentation, open source sites, and blogs. It publishes HTML, CSS, JavaScript, and Jekyll-based sites automatically on every repository push.
Is GitHub Pages completely free?
Yes, for public repositories on all plan tiers. Custom domain support and HTTPS via Let’s Encrypt are included at no cost. Private repository publishing requires GitHub Enterprise Cloud for organizations or a paid individual plan.
What is the difference between GitHub and GitHub Pages?
GitHub is a version control platform for storing and collaborating on code. GitHub Pages is a feature within GitHub that publishes a repository’s static files as a live website. One manages code. The other serves it publicly.
Can GitHub Pages run server-side code?
No. GitHub Pages serves static files only. It cannot run PHP, Node.js, Python, or connect to a database at request time. For dynamic features, developers use client-side JavaScript with third-party APIs or serverless functions hosted elsewhere.
What are the limits of GitHub Pages?
GitHub Pages sets a 1 GB site size limit, a 100 GB soft monthly bandwidth cap, and a 10 builds-per-hour limit for branch-based deployments. The build limit does not apply to custom GitHub Actions workflows.
How long does GitHub Pages take to publish?
Most sites go live within 1 to 10 minutes after a push. Jekyll builds take slightly longer than plain static file deployments. Custom GitHub Actions workflows vary depending on build complexity and Actions runner availability.
Does GitHub Pages support custom domains?
Yes. You can point a custom domain to your GitHub Pages site using a CNAME record for subdomains or 4 A records for apex domains. HTTPS is provisioned automatically via Let’s Encrypt after DNS propagation.
What is the difference between a user site and a project site on GitHub Pages?
A user site publishes at username.github.io and requires a repository named exactly username.github.io. A project site publishes at username.github.io/repo-name. Each account supports one user site but unlimited project sites.
Does GitHub Pages work with React or Next.js?
Yes, with a custom GitHub Actions workflow. React and Next.js static exports build to plain HTML and JavaScript files that GitHub Pages can serve. Next.js server-side rendering and incremental static regeneration are not supported.
What is the gh-pages branch in GitHub Pages?
The gh-pages branch is a dedicated Git branch that GitHub Pages recognizes as a publishing source for project sites. Many build tools push compiled static output to this branch automatically, keeping generated files separate from the main development branch.
Conclusion
This conclusion is for an article presenting what is GitHub Pages as a static site hosting service that removes hosting friction for developers already working inside the GitHub ecosystem.
The gh-pages branch, Jekyll build process, custom domain configuration, and GitHub Actions deployment pipeline all work together to take a repository from code to live website.
Understanding the 3 site types, the 100 GB bandwidth cap, and the difference between branch-based and Actions-driven builds helps you choose the right setup from the start.
For portfolios, open source documentation, and project sites, few hosting options match the zero-cost, version-controlled publishing workflow GitHub Pages provides.
Pick your source branch, push your static files, and the site is live.
Many of his resources are available on various design marketplaces and for free on Codepen.
Over the years, he's worked with a range of clients and contributed to design publications like Design Your Way, Designmodo, WebDesignerDepot, WPDean, Speckyboy, and Slider Revolution among others.
- How to Set Up Subscriptions on Google Play (Developer Guide) - July 12, 2026
- Why Work With a CMS Development Company for a Secure and Scalable Website? - July 12, 2026
- ADB Commands Cheat Sheet - July 11, 2026
