Host Your Website for Free with GitHub Pages

6 min read
Jan 16, 2026
Tutorial / Hosting

Complete step-by-step guide to host your HTML website for free using GitHub Pages. Learn how to deploy static websites, set up custom domains, and automate deployments with GitHub Actions.

Why GitHub Pages?

GitHub Pages is a free static site hosting service provided by GitHub. It's perfect for portfolios, documentation, blogs, and any static website. With built-in SSL, custom domain support, and seamless GitHub integration, it's the ideal choice for developers and beginners alike.

GitHub Pages Benefits

• Free hosting with 1GB storage
• 100GB bandwidth per month
• Automatic SSL certificates
• Custom domain support
• Built-in Jekyll support
• GitHub Actions integration
• Free forever for public repositories

1. Prerequisites & Setup

What You Need:

Requirements
# Essential Requirements
GitHub account (free)
Git installed on your computer
Basic HTML/CSS website files
Code editor (VS Code recommended)

# Optional but Recommended
Custom domain name
Basic Git knowledge
GitHub Desktop (for beginners)
Markdown knowledge for documentation

Project Structure Example:

my-website/
├── index.html          # Main homepage
├── about.html          # About page
├── blog/
│   ├── index.html      # Blog listing
│   └── post-1.html     # Blog post
├── css/
│   └── style.css       # Stylesheets
├── js/
│   └── script.js       # JavaScript files
├── images/             # Image assets
├── CNAME               # Custom domain file (optional)
└── .nojekyll           # Disable Jekyll processing (optional)

# Important Files:
• index.html - Required for homepage
• 404.html - Custom 404 error page (optional)
• README.md - Project documentation
• .gitignore - Git ignore file

2. Step-by-Step Deployment Guide

Method 1: Using GitHub Website (Easiest)

GitHub Web Interface
# Step 1: Create New Repository
1. Go to github.com → Click "+" → New repository
2. Repository name: username.github.io
  (Replace "username" with your GitHub username)
3. Make it Public
4. Initialize with README (optional)

# Step 2: Upload Your Website Files
1. Click "Add file" → "Upload files"
2. Drag & drop your HTML/CSS/JS files
3. Commit changes with message "Initial website upload"

# Step 3: Enable GitHub Pages
1. Go to Settings → Pages
2. Under "Source", select "main" branch
3. Select "/ (root)" folder
4. Click Save

# Step 4: Wait & Access Your Site
Wait 1-2 minutes for deployment
Visit: https://username.github.io
Green checkmark means deployed successfully

Method 2: Using Git Command Line

# Step 1: Initialize Git repository
cd /path/to/your/website
git init

# Step 2: Create GitHub repository (on website)
# Repository name: username.github.io
# Don't initialize with README

# Step 3: Connect local repository to GitHub
git remote add origin https://github.com/username/username.github.io.git

# Step 4: Add all your website files
git add .

# Step 5: Commit your changes
git commit -m "Initial website deployment"

# Step 6: Push to GitHub
git branch -M main
git push -u origin main

# Step 7: Enable GitHub Pages
# Go to Settings → Pages → Select main branch → Save

# Step 8: Verify deployment
# Wait 1-2 minutes, then visit:
# https://username.github.io

# Step 9: Update your website (when you make changes)
git add .
git commit -m "Update website design"
git push

Pro Tip: Project vs User Sites

User Site: username.github.io → Serves from main branch
Project Site: username.github.io/project → Serves from gh-pages branch
User sites must use the exact format: username.github.io
Project sites can have any repository name

3. Custom Domain Configuration

Add your own domain (like example.com) to GitHub Pages:

Domain Configuration
# Step 1: Create CNAME file
1. Create file named "CNAME" (no extension)
2. Add your domain: www.example.com
3. Place it in root folder of your repository

# Step 2: Configure DNS at your registrar
A Records (IPv4):
  @ → 185.199.108.153
  @ → 185.199.109.153
  @ → 185.199.110.153
  @ → 185.199.111.153

CNAME Record:
  www → username.github.io

# Step 3: Enable HTTPS in GitHub
1. Go to Settings → Pages
2. Under "Custom domain", enter your domain
3. Check "Enforce HTTPS"
4. Wait for SSL certificate (up to 24 hours)

# Step 4: Verify Configuration
Check DNS propagation: dnschecker.org
Test SSL: ssllabs.com/ssltest
Verify GitHub Pages recognizes your domain

Popular Domain Registrars Configuration:

  • GoDaddy: DNS Management → Add A/CNAME records
  • Namecheap: Advanced DNS → Host Records
  • Cloudflare: DNS → Add A/CNAME records (proxy disabled)
  • Google Domains: DNS → Custom resource records

4. GitHub Actions for Automated Deployments

Automate your deployment process with GitHub Actions:

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout
      uses: actions/checkout@v3
      
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        
    - name: Install dependencies (if using build tools)
      run: |
        npm ci
        npm run build
        
    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist  # Change to your build folder
        publish_branch: gh-pages  # The branch GitHub Pages uses
        
    - name: Send notification
      if: success()
      run: |
        echo "Deployment successful!"
        # Add Slack/Email notification here
        
# Simple workflow for static HTML (no build step)
name: Deploy Static HTML

on:
  push:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        
      - name: Setup Pages
        uses: actions/configure-pages@v3
        
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: '.'  # Upload entire repository
          
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Common Build Tools Integration:

  • React/Vue/Next.js: Build to static files, deploy to Pages
  • Jekyll: Native GitHub Pages support, no config needed
  • Hugo: Build with GitHub Actions, deploy to gh-pages
  • Gatsby: Build script, deploy with gh-pages-action

5. Advanced Configuration & Optimization

Performance Optimization

Performance Tips
# 1. Enable GZIP Compression
GitHub Pages automatically enables GZIP
Verify: curl -H "Accept-Encoding: gzip" -I https://your-site.com

# 2. Implement Caching Headers
Add .htaccess for Apache (won't work on GitHub Pages)
Alternative: Use Cloudflare for caching

# 3. Image Optimization
Convert to WebP format
Resize images appropriately
Use lazy loading: <img loading="lazy">

# 4. Minify Assets
Minify CSS/JS before deployment
Tools: cssnano, terser, html-minifier

# 5. CDN Integration
Use jsDelivr for libraries
Example: https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css
Cloudflare CDN for custom domain

Security Configuration

# Security Headers (add to HTML or through Cloudflare)
&lt;!-- In your HTML head section -->
&lt;meta http-equiv="Content-Security-Policy" 
      content="default-src 'self'; 
               script-src 'self' https://cdn.jsdelivr.net; 
               style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net;
               img-src 'self' data: https:;
               font-src 'self' https://cdn.jsdelivr.net;"&gt;

# Additional Security Measures:
1. Enable HTTPS enforcement in GitHub Pages settings
2. Use Subresource Integrity (SRI) for external scripts
3. Regular dependency updates
4. Security scanning with GitHub CodeQL
5. Implement rate limiting (if using APIs)

# Subresource Integrity Example:
&lt;script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js"
        integrity="sha384-geWF76RCwLtnZ8qwWowPQNguL3RmwHVBC9FhGdlKrxdiJJigb/j/68SIy3Te4Bkz"
        crossorigin="anonymous"&gt;&lt;/script&gt;

# GitHub Security Features:
• Dependabot alerts for vulnerable dependencies
• Secret scanning for exposed API keys
• Code scanning with CodeQL
• Security advisories for your repository

6. Troubleshooting Common Issues

Common Problems & Solutions

404 Error After Deployment
  • ✓ Ensure index.html exists in root
  • ✓ Check GitHub Pages source branch setting
  • ✓ Wait 5-10 minutes for propagation
  • ✓ Clear browser cache (Ctrl+Shift+R)
Custom Domain Not Working
  • ✓ Verify CNAME file exists in repository
  • ✓ Check DNS records (A and CNAME)
  • ✓ Wait 24-48 hours for DNS propagation
  • ✓ Disable Cloudflare proxy during setup
HTTPS Not Enabling
  • ✓ Wait up to 24 hours for SSL certificate
  • ✓ Ensure CNAME is properly configured
  • ✓ Check "Enforce HTTPS" in GitHub settings
  • ✓ Verify no mixed content warnings

Debugging Commands

Debugging Tools
# Check GitHub Pages Build Status
$ curl -I https://username.github.io
# Should return HTTP/2 200 for success

# Verify SSL Certificate
$ openssl s_client -connect username.github.io:443 -servername username.github.io

# Check DNS Configuration
$ dig username.github.io +noall +answer
$ nslookup username.github.io

# GitHub API - Check Pages Status
$ curl -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/username/username.github.io/pages

# Local Build Test (for Jekyll)
$ bundle exec jekyll serve
$ open http://localhost:4000

7. Best Practices & Pro Tips

Pro Tips
# 1. Organization for Multiple Projects
User site: username.github.io (main branch)
Project sites: github.com/username/project (gh-pages branch)
Access: username.github.io/project

# 2. Version Control Best Practices
Use meaningful commit messages
Create feature branches for new features
Use pull requests for review
Keep main branch always deployable

# 3. SEO Optimization
Add meta tags (title, description, keywords)
Create sitemap.xml and robots.txt
Use semantic HTML (header, main, footer, article)
Optimize images with alt text

# 4. Analytics Integration
Google Analytics 4 (free)
Plausible Analytics (privacy-focused)
Umami (self-hosted alternative)

# 5. Backup Strategy
Regular local backups
Use GitHub's built-in backup
Consider mirroring to GitLab

Alternative Free Hosting Options:

  • Netlify: More features, better for SPAs, forms support
  • Vercel: Best for Next.js, serverless functions
  • Cloudflare Pages: Built-in CDN, Workers integration
  • Render: Free tier with SSL, custom domains
  • GitLab Pages: Similar to GitHub, more CI/CD minutes

Conclusion

GitHub Pages is an excellent, free solution for hosting static websites. With its seamless integration with GitHub, automatic SSL, and custom domain support, it's perfect for personal portfolios, project documentation, blogs, and small business websites.

Remember: While GitHub Pages is great for static content, it's not suitable for dynamic applications requiring server-side processing. For those, consider services like Heroku, Railway, or Vercel Serverless Functions.

Next Steps

  • Set up your first GitHub Pages site today
  • Explore Jekyll for blog functionality
  • Integrate with Cloudflare for enhanced performance
  • Learn about GitHub Actions for CI/CD
  • Join the GitHub Community for support
0

Comments 0

Add a Comment