Complete guide to GitHub Pages in 2026. Learn how to deploy static sites, configure custom domains, optimize performance, and use GitHub Actions for CI/CD.
H
HostScout Team
··8 min read
GitHub Pages has been the go-to solution for hosting static websites directly from GitHub repositories since 2008. In 2026, it remains one of the most accessible and reliable platforms for developers, open-source projects, and documentation sites. This comprehensive guide covers everything you need to know about GitHub Pages, from basic setup to advanced configurations. ## What is GitHub Pages? GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files directly from a repository on GitHub, optionally runs them through a build process, and publishes them as a website. It’s tightly integrated with GitHub’s ecosystem, making it incredibly convenient for hosting project documentation, personal portfolios, and open-source project sites. The service is completely free for public repositories and offers 100GB of bandwidth per month. With support for custom domains, HTTPS, and Jekyll (a static site generator), GitHub Pages provides everything needed to maintain a professional web presence. ## Types of GitHub Pages Sites GitHub Pages offers three types of sites: ### 1. User/Organization Sites Created from a repository named username.github.io, these sites are published at https://username.github.io. Each GitHub account can have one user/organization site. ### 2. Project Sites Created from any repository, these sites are published at https://username.github.io/repository-name. You can have unlimited project sites. ### 3. Custom Domain Sites Any GitHub Pages site can be configured with a custom domain, appearing at https://yourdomain.com instead of the default github.io subdomain. ## Getting Started with GitHub Pages ### Method 1: Quick Setup via Repository Settings The simplest way to deploy a static site: 1. Create a new repository or navigate to an existing one
2. Add your HTML, CSS, and JavaScript files to the repository
3. Go to Settings > Pages
4. Under “Source,” select the branch you want to deploy (typically main or gh-pages)
5. Optionally specify a folder (/root or /docs)
6. Click “Save” Your site will be live within a few minutes at https://username.github.io/repository-name. ### Method 2: Using GitHub Actions For more control over the build process, use GitHub Actions: ```yaml
- Triggers on pushes to the main branch- Checks out your code- Installs Node.js and dependencies- Builds your site- Deploys to GitHub Pages ### Method 3: Using Jekyll GitHub Pages has built-in support for Jekyll, a Ruby-based static site generator. Create a basic Jekyll site: ```bash# Install Jekyllgem install bundler jekyll # Create new sitejekyll new my-sitecd my-site # Create Gemfile for GitHub Pagesecho 'source "https://rubygems.org"gem "github-pages", group: :jekyll_pluginsgem "webrick"' > Gemfile # Install dependenciesbundle install # Test locallybundle exec jekyll serve``` Your `_config.yml` for GitHub Pages: ```yamltitle: Your Site Titledescription: A concise descriptionbaseurl: "/repository-name" # for project sitesurl: "https://username.github.io" # Build settingstheme: minimaplugins: - jekyll-feed - jekyll-seo-tag - jekyll-sitemap # Exclude from buildexclude: - Gemfile - Gemfile.lock - node_modules - vendor``` ## Configuring Custom Domains ### Adding a Custom Domain 1. **Purchase a domain** from any registrar (Namecheap, Google Domains, Cloudflare, etc.) 2. **Add domain to GitHub Pages:** - Go to your repository Settings > Pages - Under "Custom domain," enter your domain - Click "Save" 3. **Configure DNS records:** For apex domain (`example.com`):
A @ 185.199.108.153
A @ 185.199.109.153
A @ 185.199.110.153
A @ 185.199.111.153
CNAME www username.github.io
A @ 185.199.108.153
A @ 185.199.109.153
A @ 185.199.110.153
A @ 185.199.111.153
CNAME www username.github.io
4. **Wait for DNS propagation** (can take up to 24 hours, usually much faster) 5. **Enable HTTPS enforcement** in repository Settings > Pages ### CNAME File When you configure a custom domain via the UI, GitHub creates a `CNAME` file in your repository root. You can also create this manually:
example.com
blog.example.com
## Supported Frameworks and Static Site Generators While Jekyll has native support, GitHub Pages works with any static site generator via GitHub Actions: ### Reactyaml
``` Or JavaScript: ```html
``` ### Sitemap Generation For Jekyll sites, add to `_config.yml`: ```yaml
plugins: - jekyll-sitemap
``` For other frameworks, generate during build: ```javascript
// generate-sitemap.js
const fs = require('fs');
const globby = require('globby'); (async () => { const pages = await globby([ 'build/**/*.html', '!build/404.html', ]); const sitemap = `
${pages.map(page => { const path = page.replace('build', '').replace('/index.html', '/'); return ` https://example.com${path}${new Date().toISOString()}`; }).join('\n')}
`; fs.writeFileSync('build/sitemap.xml', sitemap);
})();
``` ## Performance Optimization ### Image Optimization Optimize images before committing: ```bash
# Using ImageOptim CLI
npm install -g imageoptim-cli
imageoptim --imagealpha --imageoptim --jpegmini images/**/*
``` Or use a build step: ```javascript
// Using sharp in Node.js
const sharp = require('sharp');
const fs = require('fs').promises;
const path = require('path'); async function optimizeImages(dir) { const files = await fs.readdir(dir); for (const file of files) { const filePath = path.join(dir, file); const stat = await fs.stat(filePath); if (stat.isDirectory()) { await optimizeImages(filePath); } else if (/\.(jpg|jpeg|png)$/i.test(file)) { await sharp(filePath) .resize(1200, 1200, { fit: 'inside', withoutEnlargement: true }) .jpeg({ quality: 80 }) .toFile(filePath.replace(/\.\w+$/, '.optimized.jpg')); } }
}
``` ### Caching Strategy GitHub Pages automatically sets cache headers for static assets. Optimize by using fingerprinted filenames: ```javascript
// webpack.config.js
module.exports = { output: { filename: '[name].[contenthash].js', chunkFilename: '[name].[contenthash].chunk.js', },
};
``` ### Minification Ensure your build process minifies assets: ```json
// package.json
{ "scripts": { "build": "NODE_ENV=production webpack --mode production", "build:css": "postcss src/styles.css -o dist/styles.min.css --use cssnano" }
}
``` ## Monitoring and Analytics ### GitHub Traffic Insights Access basic analytics in your repository:
- Settings > Insights > Traffic
- View page views, unique visitors, and popular content ### Google Analytics Add to your HTML: ```html
``` ### Plausible Analytics (Privacy-Friendly) ```html
``` ## Security Best Practices ### Enable HTTPS Enforcement Always enable "Enforce HTTPS" in repository Settings > Pages. This:
- Encrypts data in transit
- Improves SEO rankings
- Enables modern web features ### Content Security Policy Add security headers via meta tags: ```html
``` ### Dependabot Enable Dependabot to keep dependencies updated: ```yaml
# .github/dependabot.yml
version: 2
updates: - package-ecosystem: "npm" directory: "/" schedule: interval: "weekly" open-pull-requests-limit: 10
``` ## Limitations and Workarounds ### File Size and Repository Limits - Repository size: 1 GB recommended (5 GB hard limit)
- File size: 100 MB maximum
- Bandwidth: 100 GB per month
- Build time: 10 minutes maximum **Workaround:** Use Git LFS for large files or host media on external CDN. ### No Server-Side Code GitHub Pages serves only static files. No PHP, Python, or Node.js server execution. **Workaround:** Use serverless functions (AWS Lambda, Cloudflare Workers) or JAMstack architecture with external APIs. ### Build Frequency Limits - 10 builds per hour for Actions-based deployments **Workaround:** Consolidate commits, use draft branches, or deploy manually for rapid iterations. ### No Native Redirects GitHub Pages doesn't support `.htaccess` or server-side redirects. **Workaround:** Use meta refresh or JavaScript redirects (not ideal for SEO). ## Troubleshooting Common Issues ### Site Not Updating 1. Check Actions tab for failed workflows
2. Clear browser cache (Ctrl+Shift+R)
3. Verify branch and folder settings
4. Check for `CNAME` file conflicts ### 404 Errors After Deployment 1. Ensure `baseUrl` matches repository name
2. Check file paths (case-sensitive)
3. Verify build output directory
4. Look for routing issues in SPA applications ### Custom Domain Not Working 1. Verify DNS records with `dig` command:
```bash
dig example.com +nostats +nocomments +nocmd
``` 2. Check CNAME file exists and is correct
3. Wait for DNS propagation (use https://dnschecker.org)
4. Ensure "Enforce HTTPS" is enabled after DNS propagates ## Frequently Asked Questions ### Can I use GitHub Pages for commercial projects? Yes, GitHub Pages is free for both personal and commercial use. However, you must comply with GitHub's Terms of Service and acceptable use policies. ### How do I password-protect my site? GitHub Pages doesn't support password protection natively. Options:
- Use a third-party service like Auth0 or Firebase Auth with JavaScript
- Make the repository private (requires GitHub Pro for private Pages)
- Deploy to a platform with built-in authentication ### Can I use a subdomain? Yes, you can use any subdomain with GitHub Pages by adding a CNAME record pointing to `username.github.io`. ### How do I preview changes before publishing? 1. Use GitHub Actions environments
2. Test locally with `npx serve build`
3. Create a separate repository for staging
4. Use pull request previews with services like Netlify/Vercel ### What's the difference between Jekyll and GitHub Actions deployment? - **Jekyll:** Automatic, no configuration needed, limited to Jekyll features
- **GitHub Actions:** More control, supports any framework, requires workflow setup ### Can I use multiple custom domains? No, each GitHub Pages site supports one custom domain. However, you can redirect from multiple domains using your DNS provider. ## Conclusion GitHub Pages remains one of the most reliable and developer-friendly hosting solutions in 2026. Its tight integration with GitHub's ecosystem makes it the natural choice for project documentation, personal portfolios, and open-source project sites. While it has limitations—no server-side processing, bandwidth caps, and file size restrictions—the benefits often outweigh these constraints for static sites. The ability to deploy directly from version control, combined with free HTTPS and custom domains, creates a compelling offering that's hard to beat. **Best For:**
- Project documentation
- Personal portfolios and blogs
- Open-source project sites
- Landing pages
- Static web applications **Not Ideal For:**
- E-commerce sites requiring server-side processing
- Applications with heavy media (video streaming)
- Sites requiring real-time features
- Projects needing advanced redirects and routing Whether you're an individual developer showcasing your work or an organization documenting your open-source project, GitHub Pages provides a robust, reliable, and completely free solution for static website hosting in 2026.
