Is GitHub Pages really free?

Yes. GitHub Pages is free on GitHub Free for public repositories. Publishing from private repositories needs a paid GitHub plan.

How long does GitHub Pages take to publish?

GitHub says it can take up to 10 minutes for changes to your site to publish after you push them.

Why does my GitHub Pages site show a 404?

The most common causes are a missing index.html at the top level of the publishing source, the wrong branch or folder selected in Settings, a file name with different capitalisation from the link, or a site that has not finished publishing yet.

Can I use a custom domain with GitHub Pages?

Yes. Add the domain under Settings, Pages, Custom domain, create the DNS records at your DNS provider, then tick Enforce HTTPS once the certificate is ready. Custom domains and HTTPS are free.

Can GitHub Pages handle a contact form?

Not by itself, because it only serves static files. Point the form's action at a hosted form backend such as FormSubmit and submissions are delivered by email.

Static hosting

How to Host a Website on GitHub Pages for Free (2026 Guide)

Q: What is my GitHub Pages URL?

A project site is published at https://username.github.io/repository/. A user site, from a repository named username.github.io, is published at https://username.github.io/.

Host a website on GitHub Pages for free: create a repo, add index.html, publish from a branch or GitHub Actions, add a custom domain and fix common 404s.

FormSubmit Team

Oct 14, 20265 min read

To host a website on GitHub Pages for free, create a public repository, add an index.html file, then open Settings, Pages and choose a publishing source: a branch or a GitHub Actions workflow. GitHub publishes the site at username.github.io/repository within about 10 minutes. You can add a custom domain with free HTTPS, and every push updates the site.

This tutorial walks through each step with a minimal HTML example, then covers custom domains, updates and troubleshooting. If you're still deciding where to host, our guide to free static website hosting compares GitHub Pages with the alternatives.

Limits checked 14 October 2026 against each provider's official docs. Free plans change often; check the linked pages before you commit.

What you need before you start

A free GitHub account.
A static site: HTML, CSS, JavaScript and images, or the output of a static site generator.
Optionally, a domain name if you don't want to use the github.io address.

On GitHub Free, Pages works with public repositories only. Publishing from a private repo needs a paid plan, and the published site is public either way. See GitHub Pages limits for the size, bandwidth and usage rules.

How to host a static website on GitHub Pages

These steps follow GitHub's own guide to creating a GitHub Pages site. Labels in the GitHub interface occasionally change, so check there if something looks different.

Create a public repository

Click the + icon in the top-right corner of GitHub and choose New repository. Pick the owner, give the repository a name, set visibility to Public and select Create repository.

Any name works for a project site. If you want a user site at the root of username.github.io, name the repository exactly username.github.io, in lowercase.

Add an index.html file

GitHub Pages looks for an index.html, index.md or README.md file as the entry point. It must sit at the top level of the folder you publish from. Here's a minimal page to start with:

html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>My site</title>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <h1>Hello from GitHub Pages</h1>
    <p>This site is hosted for free.</p>
  </body>
</html>

Add it with Add file then Create new file in the browser, or commit and push it from your computer with Git.

Open Settings, then Pages

In the repository, click Settings. In the sidebar, under the "Code, planning, and automation" section, click Pages.

Choose a publishing source

Under Build and deployment, set Source to one of two options:

Deploy from a branch: choose your branch (for example main) from the branch dropdown, then the folder, either / (root) or /docs. Click Save.
GitHub Actions: publish with a workflow. GitHub suggests workflow templates, or you can use your own. Choose this if you use a static site generator or push often, since the 10 builds per hour soft limit doesn't apply to custom Actions workflows.

For a plain HTML site, Deploy from a branch with / (root) is all you need.

Visit your site

GitHub says changes can take up to 10 minutes to publish. A project site appears at:

text

https://username.github.io/repository/

A user site, from a repository named username.github.io, appears at https://username.github.io/. The Pages settings screen shows the live URL once the first deployment finishes.

Using a static site generator with GitHub Pages

Branch publishing works best for hand-written HTML. If you use a generator such as Hugo, Eleventy or Astro, set the source to GitHub Actions and use one of the workflow templates GitHub suggests, or your own workflow. The workflow builds the site and deploys the output, so you don't commit generated files to the repository.

The deployed artifact needs the entry file at its top level, so make sure your build writes index.html to the root of the output folder. Actions-based publishing also avoids the 10 builds per hour soft limit, which helps if you push several times an hour.

How to add a custom domain to GitHub Pages

GitHub Pages supports custom domains with free HTTPS certificates from Let's Encrypt, as described in securing your GitHub Pages site with HTTPS.

In Settings, then Pages, enter your domain under Custom domain and click Save.
At your DNS provider, create the records GitHub's custom domain docs list: a CNAME record pointing a subdomain such as www at username.github.io, and the documented A/AAAA records for an apex domain.
Wait for DNS to propagate and for GitHub to issue the certificate.
Tick Enforce HTTPS so all visitors are redirected to the secure version.

If Enforce HTTPS is greyed out, the certificate usually isn't ready yet. Give it some time after the DNS check passes. Our guide to a free custom domain and HTTPS for a static site covers DNS in more depth.

How do you update a GitHub Pages site?

Commit and push. With Deploy from a branch, every push to the selected branch triggers a new deployment. With GitHub Actions, your workflow runs on whatever events you configure, usually a push to main.

You can follow progress in the repository's Actions tab, which shows each Pages deployment and any errors.

Troubleshooting GitHub Pages

My site shows a 404

Check that index.html sits at the top level of the publishing source: the root of the branch, or the /docs folder if you chose that.
Confirm the right branch and folder are selected under Build and deployment.
For project sites, remember the URL includes the repository name. A link to /style.css points at username.github.io/style.css, not your project. Use relative paths like style.css instead.

Some pages or images 404 but others work

GitHub Pages paths are case-sensitive. About.html and about.html are different files, and so are Logo.PNG and logo.png. This catches people who build on macOS or Windows, where the local file system usually ignores case.

My changes aren't showing

Publishing can take up to 10 minutes. Check the Actions tab to see whether the deployment finished or failed, then hard-refresh your browser to bypass the cache. GitHub suggests checking for Jekyll build errors if changes still haven't appeared after an hour.

My build or deployment failed

Deployments time out after 10 minutes, and published sites can't exceed 1 GB. Large images, videos and slow builds are the usual culprits. If you use underscores in folder names with branch publishing, Jekyll may skip them; adding an empty .nojekyll file is the common fix.

Is GitHub Pages the right free host for you?

It's a great fit for portfolios, open-source docs and personal blogs. It isn't for running an online business, and it has no previews, functions or form handling. If you need those, compare GitHub Pages vs Netlify.

Add a working contact form to your static site

GitHub Pages only serves files, so a contact form needs somewhere else to send its data. Set the form's action to a FormSubmit endpoint and each submission is emailed to you, with spam filtering built in. The free plan includes 1 form and 50 submissions a month. Our GitHub Pages contact form guide has the full code.