How to Deploy a Website on GitHub Pages: A Complete Beginner’s Guide

GitHub Pages Is the Easiest Free Hosting You’re Probably Not Using.

No monthly bill. No server. No terminal commands if you don’t want them. Just a GitHub repository, a few clicks in the settings, and your HTML file is live at a real URL — with HTTPS included.

GitHub Pages has been around for years, but a surprising number of people who could benefit from it have never heard of it. Or they’ve heard of it and assumed it was only for developers who live in the command line. It’s not. Here’s exactly how it works.

What GitHub Pages is — and what it’s actually good for

GitHub Pages is a free static website hosting service built directly into GitHub. You store your website files in a GitHub repository, configure a couple of settings, and GitHub serves the site publicly at a URL that looks like this:

[https://yourusername.github.io/your-project-name/](https://yourusername.github.io/your-project-name/)

It handles HTTPS automatically. There’s no server to configure, no database to manage, and no hosting bill at the end of the month.

It’s best suited for static websites — pages built with HTML, CSS, and JavaScript that don’t require a backend. That covers a lot of ground: portfolios, personal websites, documentation, project landing pages, event pages, small business sites, and anything else that doesn’t need a login system or a database.

If your website is a set of files rather than a running application, GitHub Pages can host it for free.

What you need before you start

Three things:

1. A free GitHub account (github.com)
2. A repository — think of it as a folder on GitHub where your files live
3. An index.html file — this is the homepage GitHub Pages will serve

No credit card. No paid plan required for public repositories.

How to deploy to GitHub Pages — step by step

Step 1: Create a repository and upload your files

Log in to GitHub and create a new repository. Give it a name — this will become part of your URL, so keep it clean and lowercase (e.g., my-portfolio or project-name).

Set the repository to Public. GitHub Pages works on private repositories only with a paid plan.

Upload your HTML files. The most important thing: your main page must be named index.html. If GitHub Pages can't find a file with that name at the root of your repository, visitors will get a 404 error.

This is where most people quietly fail — they upload a file named homepage.html or landing.html and spend an hour wondering why their site isn't working.

Step 2: Open the GitHub Pages settings

Inside your repository, click Settings in the top navigation bar. Then find Pages in the left sidebar.

Step 3: Choose your source branch

Under Build and deployment, select Deploy from a branch. Then choose your branch — main or master depending on when the repository was created.

For the folder, leave it set to /(root) unless you've stored your files inside a /docs subfolder.

Step 4: Save — then wait

Click Save. GitHub will start building and deploying your site.

Here’s where patience matters: the first deployment usually takes 1–3 minutes. Refresh the Settings → Pages section after a couple of minutes — GitHub will show a green banner with your live URL when it’s ready.

Don’t keep clicking things while waiting. People assume something is broken and start changing settings, which just restarts the process.

Step 5: Open your live site

Your URL is ready at [https://yourusername.github.io/repository-name/](https://yourusername.github.io/repository-name/)

Open it, verify everything looks right, then share it.

Updating your site later

Once your site is live, updating it is simple: upload a new version of your file to the same repository and branch. GitHub Pages detects the change and re-deploys automatically — usually within a minute or two.

No re-configuring. No re-deploying from scratch. Just push the updated file and the live site reflects the change.

Want to skip all the manual steps?

The process above works. But it has real friction — especially if you’re publishing pages regularly.

Every time you want to deploy, you’re switching between tools: your editor or AI tool, then GitHub to upload the file, then Settings to verify, then waiting, then checking the live URL. That’s 6–8 manual steps that reset every single time.

**HTML Deployer** is a free Chrome extension that compresses this entire process into one click.

Here’s how it works:

1. Open any HTML file — whether you wrote it yourself, downloaded a template, or got it from an AI tool
2. Click the HTML Deployer button in your browser
3. Preview how your page looks on desktop, tablet, and mobile
4. Select GitHub Pages as your publish target
5. Click Deploy — your page goes live in seconds, and you get a live URL plus a QR code automatically

[embed]

No copying files. No switching between tabs. No waiting to see if the upload worked.

For anyone deploying more than a few pages, the time saved compounds quickly. A task that used to take 15–20 minutes — create repo, upload file, configure settings, wait, verify — becomes something you do in under a minute.

HTML Deployer also supports Netlify, Vercel, FTP hosting, and self-hosted servers, so you’re not locked into one platform. Full setup guide for GitHub Pages specifically: https://backrun.co/htmldeployer/help.html#github

Custom domains

If you want your site at yourname.com instead of yourusername.github.io/project, GitHub Pages supports custom domains.

You’ll need to own the domain, add a CNAME file to your repository with your domain name, and update the DNS settings at your registrar to point to GitHub's servers. HTTPS works automatically through GitHub's integration with Let's Encrypt once the domain is connected.

What GitHub Pages doesn’t do

It’s worth being clear about the limits.

GitHub Pages hosts static files only:

• No PHP, Python, or other server-side code
• No databases or user logins (unless using a third-party service)
• No server-side form processing (workarounds exist via services like Formspree)

If your project needs a backend, look at Railway, Render, or Heroku instead. But for a large percentage of websites people actually want to build and share — portfolios, landing pages, documentation, event pages — static hosting is entirely sufficient.

GitHub Pages vs. Netlify

Both are free. Both support custom domains. Both work well for static HTML.

• GitHub Pages is the better choice if your files are already in a GitHub repository, or if you want version control as part of the same workflow.
• **Netlify** is faster for a first-time setup — you can drag and drop a folder onto their interface and get a live URL in seconds, no repository required.

Neither is wrong. Many people use both depending on the project.

A few things worth knowing before you share your link

• Wait before sharing. After the first deployment, give it 2–3 minutes before sending the link to anyone. GitHub Pages doesn’t go live instantly.
• The URL is public. Any repository with GitHub Pages enabled is publicly accessible at its URL. Don’t publish anything sensitive.
• Hard refresh if you’re not seeing updates. After pushing a file change, use Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac) to force your browser to load the latest version.

The bottom line

GitHub Pages removes the two biggest friction points in getting a website live: cost and server complexity.

For portfolios, documentation, project pages, and static sites of any kind, it’s one of the best free options available. The update workflow is fast enough for active, ongoing projects — and the learning curve is short enough that most people have their first site live within 20 minutes of creating a GitHub account.

After that first time, it’s a tool you’ll keep coming back to.