How to Host a Webpage on GitHub for Free
What is GitHub Pages and Why Should You Care
GitHub Pages is a free static site hosting service built directly into GitHub. You upload your HTML, CSS, and JavaScript files to a repository, and GitHub serves them live on the web. No servers to manage, no hosting fees, no complicated setup.
It's been around since 2008 and powers millions of websites. If you want to host a simple webpage, portfolio, or documentation site without paying for hosting, this is the most reliable free option available.
What You Need Before Starting
- A GitHub account (free tier works fine)
- Git installed on your computer
- Basic HTML/CSS files ready to upload
- 10-15 minutes of free time
If you don't have Git installed, download it from git-scm.com. The installer works fine with default settings for most users.
How to Host Your First Webpage on GitHub
Step 1: Create a New Repository
Log into GitHub and click the "New repository" button in the top-left corner.
For GitHub Pages to work automatically, you must name your repository in this specific format:
username.github.io
Replace "username" with your actual GitHub username. If your username is "johnsmith", the repository name should be johnsmith.github.io. This naming convention is what triggers GitHub's automatic page generation.
Step 2: Upload Your Files
On your new repository page, click the "uploading an existing file" link.
Drag and drop your index.html file along with any CSS, images, or JavaScript files you need. Your main page must be named index.html — GitHub looks for this file specifically.
Scroll down, add a commit message like "Initial commit", and click "Commit changes".
Step 3: Wait About 2 Minutes
GitHub needs a moment to build and deploy your site. Check the repository Settings tab, scroll down to "GitHub Pages" section. You'll see a green banner confirming your site is live once it's ready.
Your site will be live at https://username.github.io
Hosting a Project Page (Different Repository)
You don't have to use your username repository. You can host pages from any repository by enabling GitHub Pages in that repo's settings.
This is useful for:
- Landing pages for specific projects
- Documentation sites
- Team or event pages
- Testing designs before moving them elsewhere
To set this up, go to your repository's Settings → Pages. Under "Source", select your branch (usually "main") and the folder containing your files (root or /docs).
The URL will be https://username.github.io/repository-name
Adding a Custom Domain
GitHub Pages supports custom domains. This costs you the price of domain registration (usually $10-15 per year) but keeps hosting free.
In your repository's Settings → Pages:
- Enter your domain name in the "Custom domain" field
- Click Save
- Add the DNS records GitHub specifies to your domain registrar
You'll need either:
- An A record pointing to GitHub's IP addresses
- A CNAME record pointing to username.github.io
DNS changes can take up to 48 hours to propagate, though it usually happens within a few hours.
Common Problems and Fixes
404 Error After Upload
Your main file must be named index.html, not home.html or main.html. GitHub looks for index.html specifically.
CSS Not Loading
Check your file paths. If your CSS file is in a folder called "css", your link tag should be:
<link rel="stylesheet" href="/css/style.css">
Make sure case sensitivity matches — Style.css and style.css are different on GitHub's servers.
Site Not Updating
GitHub caches aggressively. Push a small change (like adding a space to index.html) and wait 3-5 minutes. If it still doesn't update, check that GitHub Pages is enabled in your repository settings.
Branch or Folder Selected Wrong
In Settings → Pages, verify you've selected the correct branch and folder. Most beginners accidentally select a "docs" folder that doesn't exist yet.
GitHub Pages vs. Alternatives
| Service | Cost | Ease of Use | Custom Domains | Best For |
|---|---|---|---|---|
| GitHub Pages | Free | Medium | Yes (free) | Static sites, portfolios, docs |
| Netlify | Free tier available | Easy | Yes (free) | JAMstack sites, modern frameworks |
| Vercel | Free tier available | Easy | Yes (free) | React/Next.js projects |
| Surge | Free | Easy | Yes (free) | Quick CLI deployments |
| Traditional Hosting | $5-20/month | Varies | Usually included | Databases, server-side code |
GitHub Pages wins on price and integration if you're already using Git. Netlify and Vercel are easier for non-technical users or if you're using modern static site generators.
What GitHub Pages Cannot Do
- Run server-side code (PHP, Python, Node.js backends)
- Host databases
- Handle user authentication natively
- Process forms without third-party services
- Stream video or serve large files efficiently
It's strictly for static content — HTML, CSS, JS, images, and fonts. If you need dynamic features, you'll need to integrate third-party services or look at other hosting options.
Quick Checklist Before Going Live
- Repository named username.github.io (for user pages)
- Main file is index.html in root folder
- All asset paths are correct (case-sensitive)
- GitHub Pages enabled in Settings
- CNAME file added if using custom domain
Once these are confirmed, your site should be accessible within minutes. GitHub's infrastructure is reliable — your page will stay up as long as GitHub does, which is to say, it will stay up.