How to Deploy a Website on GitHub Pages: 6 Steps (2026)

Learning how to deploy a website on GitHub Pages is one of the fastest ways for a beginner to get a real site live on the internet. You do not need a credit card, a server, or any backend knowledge. If you have a folder with HTML, CSS, and JavaScript files, you can turn it into a public website in under ten minutes, completely free.

In this guide, I will walk you through every step as a beginner: creating a GitHub account, uploading your files, switching on GitHub Pages, and opening your live site. Along the way, you will also learn how to fix the most common errors new users hit, like the dreaded 404 page after deployment.

In This Guide

What Is GitHub Pages (and When to Use It)

Typing git push commands in terminal to deploy website on GitHub Pages

GitHub Pages is a free hosting service built into GitHub. It takes the files stored in a GitHub repository and serves them as a static website. “Static” means the site is made of fixed files — HTML, CSS, JavaScript, images — with no server-side code like PHP or a database.

That makes GitHub Pages perfect for portfolios, resumes, documentation, landing pages, and small projects. It is not the right tool for a WordPress blog, an online store, or anything that needs a login system, because it cannot run server code. If you want to see how GitHub Pages compares to other free options, read our guide on how to host a static website for free.

What You Need Before You Start

You only need two things:

A GitHub account. Sign up free at github.com if you do not have one yet.
Your website files. At minimum, an index.html file. Your CSS, JavaScript, and images go alongside it.

Before uploading, double-check that your main page is named exactly index.html (all lowercase). GitHub Pages looks for this file first, and a different name like Index.html or home.html is one of the most common beginner mistakes.

Step 1: Create a GitHub Account and Repository

A repository (or “repo”) is just a storage folder on GitHub for your project. Here is how to create one:

Sign in to GitHub and click the + icon in the top-right corner, then New repository.
Give it a name. A special trick: if you name it yourusername.github.io (using your actual username), GitHub will serve the site at that exact address. Any other name works too — the site will live at yourusername.github.io/repo-name.
Leave it Public. GitHub Pages only publishes public repositories on free accounts.
Tick Add a README file if you want, then click Create repository.

Step 2: Upload Your Website Files

You can upload files through the browser, but learning the Git method now will save you time later — and it is the same workflow professional developers use.

Option A: Upload in the browser (easiest)

Open your new repository and click Add file, then Upload files.
Drag in your index.html, CSS, JS, and images. Keep the same folder structure you used locally.
Click Commit changes.

Option B: Push with Git commands (recommended)

If Git is installed on your computer, open a terminal inside your website folder and run these commands one by one:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/your-repo-name.git
git push -u origin main

Replace yourusername and your-repo-name with your real values. Git will ask for your GitHub username and a personal access token as the password (GitHub no longer accepts account passwords for pushes). After this, every future update is just git add ., git commit -m "update", git push.

Step 3: Turn On GitHub Pages

Uploading files alone does not publish the site. You have to enable Pages:

In your repository, click Settings (the tab at the top).
In the left sidebar, click Pages.
Under Build and deployment, set the source to Deploy from a branch.
Choose the main branch and the /(root) folder, then click Save.

That is the whole “deployment”. There is no build step for plain HTML sites — GitHub simply starts serving your files. For the official walkthrough with screenshots, see the GitHub Pages quickstart docs.

Step 4: Open Your Live Website

After saving, GitHub shows a banner: “Your site is ready to be published at https://yourusername.github.io/repo-name/”. The first build usually takes one to three minutes. Open the link, and if you see your site, congratulations — you have deployed a website on GitHub Pages.

If it shows a 404, wait a couple of minutes and hard-refresh (Ctrl+Shift+R). New deployments sometimes need a moment before the address goes live. If it still fails after five minutes, jump to the mistakes section below — the fix is usually small.

How to update your site later

Every time you push new commits to the main branch, GitHub rebuilds and republishes the site automatically. There is nothing else to click. This is why the Git workflow from Step 2 is worth learning: updating your site becomes a 10-second habit.

Bonus Step: Add a Custom Domain and HTTPS

The default github.io address works fine for practice, but a custom domain like myportfolio.com looks more professional.

Buy a domain from any registrar.
Add a file named CNAME (no extension) to your repository’s root folder, containing just your domain name, e.g. myportfolio.com.
At your registrar, point the domain to GitHub Pages with the DNS records from GitHub’s docs.
Back in Settings > Pages, tick Enforce HTTPS. GitHub gives you a free certificate automatically.

HTTPS matters: browsers flag non-HTTPS sites as “Not secure”, which hurts trust and SEO.

Common Mistakes and How to Fix Them

404 File not found after deploying

The number-one cause is a missing or misnamed index.html. Check that the file is in the repository root (not inside a subfolder) and spelled exactly index.html. Also confirm Pages is set to the branch you actually pushed to — beginners sometimes push to master while Pages watches main.

Images or CSS not loading

This is almost always a path problem. If your HTML references /style.css (an absolute path), the browser looks at the domain root, but project sites live at username.github.io/repo-name/. Use relative paths like style.css or css/style.css instead.

Site looks different from your local version

File names are case-sensitive on GitHub Pages. Style.css and style.css are different files to the server, even though Windows treats them the same. Keep all file names lowercase to avoid this.

Changes not showing up

First, hard-refresh to bypass your browser cache. If the change still is not there, check the Actions tab in your repo — a failed Pages build will show a red X with an error log telling you exactly what went wrong.

GitHub Pages Limits You Should Know

Free hosting comes with fair-use limits:

1 GB repository size and a soft 100 MB per-file limit. Keep videos and huge images elsewhere.
100 GB bandwidth per month — plenty for personal sites, not for viral traffic.
10 builds per hour. Pushing 20 commits in five minutes will queue them.
No server-side code. No PHP, Python backends, or databases. Need a form? See our guide on building an HTML contact form without a backend, which pairs perfectly with GitHub Pages sites.
No server config. You cannot set custom redirect rules or server headers beyond what GitHub provides.

Frequently Asked Questions

Is GitHub Pages really free?

Yes. Public repositories get free hosting with generous limits. Private repositories can also use Pages on paid GitHub plans, but for beginners the free tier is all you need.

Can I deploy a JavaScript framework site like React on GitHub Pages?

Yes. Build your project locally (for example, npm run build in a React app) and deploy the contents of the build output folder. GitHub Pages serves the compiled static files just like plain HTML.

How long does it take for changes to go live?

Usually under two minutes after you push. The first deployment can take a little longer. Watch the Actions tab if you want to see the build happen in real time.

Does GitHub Pages support HTTPS?

Yes, and it is enabled by default on github.io addresses. For custom domains, tick “Enforce HTTPS” in Settings > Pages after your DNS is set up — the certificate is issued automatically and renews itself.

Can I use GitHub Pages for a client project?

For small static client sites, absolutely — just remember the site’s source code will be public unless you use a paid plan. Never commit API keys, passwords, or private data to a Pages repository.

What happens if I delete the repository?

The site goes offline immediately. If you only need to take the site down temporarily, disable Pages in Settings > Pages instead of deleting the repo.

Key Takeaways

GitHub Pages turns any public repository into a free static website — no server or payment needed.
Name your homepage exactly index.html and keep file names lowercase to avoid 404s.
Push to the main branch and GitHub rebuilds your live site automatically.
Use relative file paths so CSS and images load correctly on project subpaths.
Enable HTTPS, and add a custom domain when you want a professional address.

Conclusion

You now know how to deploy a website on GitHub Pages step by step: create a repo, upload your files, flip the Pages switch, and open your live URL. The whole process costs nothing and takes minutes once you have done it once.

From here, the best next move is practice — deploy your portfolio, a landing page, or a small experiment, and get comfortable with the push-to-publish loop. Once your site is live, you can level up the design with touches like a dark mode toggle with JavaScript or clean up your markup using proper HTML structure. Your first live site is the hardest one; every deployment after this gets easier.