How to Host on GitHub- Deployment Guide

What GitHub Pages Actually Is

GitHub Pages is free static site hosting. That's it. Your HTML, CSS, and JS files sit on GitHub's servers, and anyone can access them via a URL. No server-side code, no database, just files served directly to browsers.

This works perfectly for:

You're limited to static content. If you need a backend, look elsewhere.

Prerequisites

Before you start, you need two things:

If you don't have Git, download it from git-scm.com. The install is straightforward. Next, configure it with your GitHub credentials:

git config --global user.name "Your Username"
git config --global user.email "your@email.com"

Creating Your Repository

Log into GitHub and hit the New repository button. Name it something simple — this name becomes part of your URL.

The format is: username.github.io

For example, if your username is janedoe, your repo should be named janedoe.github.io. This makes your site live at https://janedoe.github.io automatically.

You can also host from a different repo name, but then your site lives at https://username.github.io/repo-name. That's ugly. Just name the repo right from the start.

Pushing Your Code

Clone the repo to your local machine:

git clone https://github.com/username/username.github.io.git

Navigate into the folder and add your files. A basic setup looks like this:

index.html
styles.css
script.js
images/

Your index.html is the homepage. GitHub serves this automatically when someone visits your URL.

Once your files are in the folder, run these commands:

git add .
git commit -m "Initial commit"
git push -u origin main

Your code is now on GitHub. The site isn't live yet — you still need to enable Pages.

Enabling GitHub Pages

Go to your repository on GitHub. Click the Settings tab, then scroll down to Pages in the sidebar.

Under Source, select:

Click Save. GitHub will start deploying your site. This takes 1-2 minutes, sometimes longer.

Your site appears at https://username.github.io once it's ready. Check the Pages section for status updates.

Using a Project Repo Instead

If you named your repo something else, you can still host from it. Go to Settings → Pages, then select your branch and folder. Your site will be at https://username.github.io/repo-name.

This is fine for project documentation. For a personal site or portfolio, just use the username.github.io naming convention.

Adding a Custom Domain

Want your site at www.yoursite.com instead of username.github.io? You can do that.

Step 1: Buy a domain

Get one from any registrar — Namecheap, Google Domains, Cloudflare. They're usually $10-15 per year.

Step 2: Add the domain in GitHub

In Settings → Pages, type your domain under Custom domain. Hit Save. GitHub creates a file called CNAME in your repo automatically.

Step 3: Configure DNS records

Go to your domain registrar and add these records:

DNS changes take up to 24 hours to propagate. Your custom domain will work eventually.

GitHub Pages vs. Other Hosting Options

Here's how GitHub Pages stacks up against alternatives:

Feature GitHub Pages Netlify Vercel Traditional Hosting
Cost Free Free tier available Free tier available $5-20/month
Custom domain ✅ Yes ✅ Yes ✅ Yes ✅ Yes
HTTPS ✅ Free (auto) ✅ Free ✅ Free Usually extra
Server-side code ❌ No ❌ No Limited ✅ Yes
Build tools Jekyll only Any Any Any
Private repos Only paid Paid only Paid only N/A

GitHub Pages is the cheapest option for static sites. If you need server-side features or more build options, Netlify or Vercel are better choices.

Common Problems and Fixes

Site not updating

GitHub caches aggressively. After pushing changes, force a redeploy by going to Settings → Pages and clicking Re-run under Source, or toggle the branch and save again.

404 errors on pages

Your pages need the .html extension if you're linking directly. GitHub Pages serves index.html automatically for directories, but other files need the full extension or proper routing.

CSS not loading

Check your file paths. Links should be relative, like href="styles.css", not absolute. If you're using a base URL, make sure your links account for it.

Custom domain SSL issues

GitHub enables HTTPS automatically for custom domains, but it can take up to 24 hours after DNS propagates. If it still doesn't work, uncheck Enforce HTTPS, save, wait a minute, then re-check it.

Jekyll Support

GitHub Pages has built-in Jekyll support. If you push a Jekyll-formatted site, GitHub builds it automatically. This means you can use Markdown files instead of raw HTML.

Jekyll isn't required. Plain HTML works fine and deploys faster. Only use Jekyll if you want templating and Markdown support.

Keeping Your Site Secure

Your GitHub Pages site is public by default. Anyone can view your source code at github.com/username/username.github.io.

Don't store sensitive data in your repo — API keys, passwords, private info. Use environment variables or a backend service for anything that needs to stay secret.