What Is GitHub Pages? Free Hosting for Your First Website

Why AI Coders Need This

When you're learning to code with AI help, you hit a wall fast: you've got a working site on your laptop, but you have no idea how to make it visible to anyone else. Most hosting guides assume you know what a server is, what SSH means, or how deployment pipelines work.

GitHub Pages skips all of that. If you already use GitHub to store your code — which you should be — then you're one settings toggle away from a live website. No new accounts, no new tools, no new concepts to learn first.

It's also the easiest way to build a portfolio that proves you can ship things. Chuck, a designer who started coding six months ago with AI assistance, used GitHub Pages to publish his first three projects before he ever touched Vercel. "I just needed something live I could show people. GitHub Pages meant I didn't have to learn deployment before I learned coding."

That's the right order. Hosting comes after building. GitHub Pages makes hosting trivially easy so it doesn't block you.

What GitHub Pages Does

GitHub Pages takes files from a GitHub repository and serves them as a website. That's the whole thing.

You put your index.html, your CSS, your JavaScript, your images into a repo. You go to Settings → Pages and tell GitHub which branch to publish from. Within a minute or two, your files are live at a URL that looks like this:

https://yourusername.github.io/your-repo-name/

If you create a special repo named yourusername.github.io, that repo's contents become your root site at:

https://yourusername.github.io/

Every time you push new code to that branch, GitHub Pages automatically updates the live site. Usually within 30–60 seconds. There's no "deploy" button you have to click. Push to GitHub, the site updates. That's it.

What "static" actually means

GitHub Pages serves static files. Static means the files go to the browser exactly as they are. What you put in the repo is what the browser gets.

This is different from a dynamic server, which generates pages on the fly based on database queries, user sessions, or business logic. A static site doesn't do any of that — the HTML file exists on disk and gets sent to whoever requests it.

Static doesn't mean boring. You can have JavaScript that fetches data from external APIs, animations, interactive components, contact forms (with a third-party form service), and anything else that runs in the browser. The limitation is only on the server side — you can't run Node.js, Python, or any server-side code on GitHub Pages.

What GitHub Pages gives you for free

• HTTPS by default — your site gets a valid SSL certificate automatically
• Global CDN — GitHub serves your files from edge locations worldwide, so it loads fast everywhere
• Automatic deploys — push to your branch, site updates
• Custom domains — point your own domain at it with a free HTTPS cert
• Jekyll support — GitHub Pages has built-in support for Jekyll, a static site generator, if you want Markdown-based blogging without a build step

How to Set It Up

Three steps. No terminal required if your files are already in a GitHub repo.

Step 1: Push your files to GitHub

Your site needs to live in a GitHub repository. If you're not using Git yet, this is the moment to start — but GitHub's web interface also lets you drag and drop files directly into a repo without touching the terminal.

The key file is index.html at the root of your repo. That's what GitHub Pages will serve when someone visits your URL. Everything else — CSS files, JavaScript, images, other HTML pages — goes in the same repo alongside it.

A minimal repo looks like this:

my-portfolio/
├── index.html
├── style.css
├── script.js
└── images/
    └── headshot.jpg

Step 2: Enable Pages in repo settings

1. Go to your repository on GitHub.com
2. Click the Settings tab (the gear icon, top right of the repo)
3. Scroll down the left sidebar to Pages
4. Under "Source," choose Deploy from a branch
5. Select your branch (usually main) and the / (root) folder
6. Click Save

That's it. GitHub will show you a banner that says "Your site is live at https://yourusername.github.io/your-repo/" within about a minute.

Step 3: Push updates to keep it live

From here, your deployment workflow is just using Git normally. Make changes, commit, push to the branch you selected in Step 2, and GitHub Pages picks it up automatically. There's no separate deploy command, no dashboard to watch, no build logs to check (unless something breaks).

# Make a change to your site
git add .
git commit -m "Update portfolio with new project"
git push origin main
# Site updates in ~60 seconds

Custom Domains

Your GitHub Pages URL (yourusername.github.io/repo-name) works fine for sharing, but if you want something like chuckdesigns.com, GitHub Pages supports custom domains at no extra charge.

You'll need to buy the domain from a registrar — Porkbun, Namecheap, and Cloudflare Registrar are popular options and typically cost $10–$15 per year for a .com.

Setting up a custom domain

1. Add a CNAME file to your repo. Create a file literally named CNAME (no extension) in the root of your repo. Inside it, put your domain on a single line: chuckdesigns.com
2. Configure DNS at your registrar. You need to point your domain to GitHub's servers. For an apex domain (yoursite.com), add four A records pointing to GitHub's IPs. For a www subdomain, add a CNAME record pointing to yourusername.github.io.
3. Enable the custom domain in GitHub Settings. Go to Settings → Pages, enter your domain in the Custom Domain field, click Save.
4. Enable HTTPS. Once DNS propagates (can take up to an hour), check the "Enforce HTTPS" checkbox. GitHub provisions a free Let's Encrypt certificate automatically.

GitHub's IP addresses for A records (as of 2026):

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

What You Can and Can't Host

Understanding this line will save you a lot of frustration. GitHub Pages is not a general-purpose web server. It has one job: serve files.

What works great

• Portfolio sites — HTML/CSS/JS showcasing your work
• Personal blogs — especially with Jekyll or a static site generator
• Project documentation — many open-source projects host their docs on GitHub Pages
• Landing pages — simple one-page marketing sites
• Resume/CV sites — a single-page site beats a PDF every time
• JavaScript apps that call external APIs — a weather app, a GitHub profile viewer, anything where the backend is someone else's API
• React apps built with Vite or Create React App — with a small config tweak for routing

What doesn't work

• Node.js / Express servers — no server-side execution
• Databases — no PostgreSQL, SQLite, MongoDB, nothing
• User authentication you control — you can use a third-party auth service like Auth0, but you can't run your own auth server
• Server-side API routes — no /api/send-email endpoint that runs code
• Next.js with server components or API routes — the static export mode works, but not the full framework
• PHP, Python, Ruby — none of it executes
• File uploads to your server — there's no server to receive them

GitHub Pages vs Vercel vs Netlify

All three serve static sites for free. The differences matter once you start building anything beyond basic HTML.

When to use GitHub Pages

You're writing plain HTML, CSS, and JavaScript. You want zero configuration. You already use GitHub and don't want to connect another service. You're building a portfolio, a documentation site, or a simple project showcase.

When to graduate to Vercel

Your project uses a framework that needs a build step — Next.js, Astro, SvelteKit, Nuxt. You want deploy previews (a live URL for every pull request). You need serverless functions for a lightweight backend. Vercel is the natural next step and is almost as easy to set up.

When to consider Netlify

Same use cases as Vercel. Netlify has slightly different strengths — better form handling built in, a more mature plugin ecosystem, and some people prefer its UI. Either works; the choice is often personal preference.

What AI Gets Wrong About GitHub Pages

AI tools are useful for setting up a GitHub Pages site, but they make a few consistent mistakes worth knowing about.

Generating server-side code for a static host

Ask AI to "add authentication" or "build a contact form" and it will often generate Express routes, Node.js handlers, or other server-side code. None of this runs on GitHub Pages. When prompting AI, always specify: "This is a static GitHub Pages site. No backend code. Use browser-only solutions or third-party services."

Using Next.js without static export

AI commonly suggests Next.js for portfolios and blogs. Next.js works on GitHub Pages only with output: 'export' in your next.config.js, which disables server-side rendering and API routes. If AI generates a Next.js project without that config, it won't work on GitHub Pages. Either add the config or switch to Vercel, which runs Next.js natively.

Forgetting the base URL for non-root repos

When your site is at yourusername.github.io/my-portfolio/ (not the root), all your asset paths need to include /my-portfolio/ as a prefix. AI often generates paths like /style.css which break because the actual path is /my-portfolio/style.css. Fix: use relative paths (./style.css) or set the base URL in your framework's config.

Suggesting GitHub Actions when you don't need them

For a basic static site, you don't need a GitHub Actions workflow. Just deploy from a branch. AI sometimes suggests elaborate CI/CD pipelines for sites that need none. If you're not using a build step, ignore any suggestions involving .github/workflows/.

Outdated Pages configuration

GitHub changed how Pages configuration works in 2022 — the old way used a gh-pages branch, the new way uses the Settings UI to select any branch. AI sometimes still generates gh-pages branch workflows when they're not needed. The Settings → Pages → Deploy from branch method is simpler and current.

Frequently Asked Questions

What to Learn Next