Last updated: 23 October 2026
GitHub Pages hosts static websites (HTML, CSS and JavaScript, with no server-side code) for free, with HTTPS and a github.io address. It's the quickest way to put a portfolio, project demo or documentation online. This guide takes you from an index.html on your computer to a live site, then covers custom domains, React or Vite projects, and the errors you're most likely to hit.
Contents
- User site or project site?
- Create the repository
- Upload your files
- Turn on GitHub Pages
- Update the site
- Use your own domain
- React, Vite and other build tools
- Troubleshooting
- Limits and FAQs
1. User site or project site?
Decide this first, because it sets the repository name and your URL:
| User site | Project site | |
|---|---|---|
| Repository name | Exactly yourusername.github.io | Anything, e.g. portfolio |
| Your URL | https://yourusername.github.io | https://yourusername.github.io/portfolio/ |
| How many | One per account | One per repository, as many as you like |
| Good for | Your main portfolio | Individual project demos |
On a free GitHub account, the repository must be public. Pages from private repositories needs a paid plan (GitHub Pro, Team or Enterprise).
2. Create the repository
- Sign in to GitHub, click the + in the top-right corner and choose New repository.
- Enter the repository name from the table above.
- Select Public. If your files are already on your computer, don't add a README; an empty repository is easier to push to.
- Click Create repository.
3. Upload your files
Your homepage must be called index.html (all lowercase) and sit at the top level of the repository. A minimal project looks like this:
my-site/
├── index.html
├── about.html
├── css/
│ └── style.css
└── images/
└── profile.jpg
Option A: in the browser. On the new repository's page, click uploading an existing file, drag in your files and folders, and click Commit changes. Fine for a one-off.
Option B: with Git (better, because updating later is one command). In your project folder:
git init
git add .
git commit -m "First version of my site"
git branch -M main
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main
GitHub no longer accepts your account password when you push. Use a personal access token or an SSH key; my guide to pushing files to GitHub from the terminal sets this up step by step.
4. Turn on GitHub Pages
- In the repository, open Settings.
- In the left sidebar, under Code and automation, click Pages.
- Under Build and deployment → Source, choose Deploy from a branch.
- Under Branch, select
mainand the folder/ (root). (Choose/docsonly if your site is inside adocsfolder.) - Click Save.
GitHub starts a deployment. You can watch it in the Actions tab, where it appears as pages build and deployment: a yellow dot means it's running, a green tick means it's live. This usually takes under a minute. Go back to Settings → Pages and you'll see "Your site is live at…" with your URL and a Visit site button.
5. Update the site
Every push to main redeploys automatically:
git add .
git commit -m "Update about page"
git push
Wait for the green tick in the Actions tab, then refresh. If you still see the old version, do a hard refresh (Ctrl+Shift+R) or open the site in a private window; your browser may have cached it.
6. Use your own domain
You can serve the site at your own domain, such as www.yourname.in, still free on GitHub's side.
- Verify the domain first (recommended). In your GitHub account Settings → Pages, add and verify the domain. This stops anyone else from claiming it on GitHub if your DNS ever points there without a site.
- Add DNS records at your domain registrar (GoDaddy, Hostinger, Cloudflare and so on):
- For
www.yourname.in: a CNAME record with hostwwwpointing toyourusername.github.io. - For the root domain
yourname.in: four A records pointing to:
Optionally, for IPv6, four AAAA records:185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.1532606:50c0:8000::153,2606:50c0:8001::153,2606:50c0:8002::153,2606:50c0:8003::153.
- For
- Enter the domain in the repository's Settings → Pages → Custom domain and click Save. For branch deployments, GitHub adds a
CNAMEfile to your repository automatically; pull it (git pull) before your next push. - When the DNS check passes, tick Enforce HTTPS. The certificate can take from a few minutes up to a day while DNS updates.
You can check your DNS from a terminal with dig www.yourname.in +short. These values come from GitHub's custom domain documentation, so check there if anything changes.
7. React, Vite and other build tools
If your site has a build step, GitHub Pages must serve the built files (the dist folder), not your source code. Don't commit dist by hand; let GitHub Actions build it:
- For a project site, tell Vite the sub-path in
vite.config.js:base: "/your-repo/". Otherwise CSS and JavaScript load from the wrong place and you get a blank page. - In Settings → Pages → Source, choose GitHub Actions instead of "Deploy from a branch".
- Use GitHub's suggested static-site workflow, or follow Vite's GitHub Pages guide, which gives a ready-made workflow file.
React Router note: GitHub Pages has no server-side routing, so refreshing /about returns 404. Use HashRouter, or a host that supports rewrites, such as Firebase Hosting.
8. Troubleshooting
| Problem | Likely cause and fix |
|---|---|
| 404 "There isn't a GitHub Pages site here" | No index.html in the selected folder, the wrong branch or folder is selected, or the first deploy hasn't finished. Check Settings → Pages and the Actions tab. |
| Page loads but has no styling or images | Paths are wrong. On a project site, a link like /css/style.css points to the domain root; use a relative path like css/style.css. |
| Works locally, broken online | File names are case-sensitive on GitHub Pages: Logo.png and logo.png are different files. Windows and macOS hide this. |
| Blank page with a React or Vite app | Missing base in vite.config.js, or you deployed source files instead of dist (see section 7). |
Files or folders starting with _ are missing | Branch deployments run Jekyll, which skips them. Add an empty file named .nojekyll to the root. |
| Red cross in the Actions tab | Open the failed run and read the log; it names the file or step that broke. |
remote: Support for password authentication was removed | Use a personal access token or SSH key instead of your password. |
9. Limits and FAQs
Is GitHub Pages really free?
Yes, for public repositories. GitHub sets soft usage limits, such as a maximum published site size and monthly bandwidth; see GitHub Pages limits for current numbers. Personal sites, portfolios and project demos stay well within them.
Can I use it for a business or online shop?
GitHub Pages isn't meant for running an online business, e-commerce or handling payments. Use it for portfolios, documentation and project sites.
Can it run PHP, Node.js or a database?
No. It only serves static files. For a backend, call an API from JavaScript (for example Firebase), or use a host that runs server code.
Can I keep the repository private?
Only on a paid plan (Pro, Team or Enterprise). On a free account, both the repository and the site are public.
Related: Pushing files to GitHub from the terminal · Create a React app with Vite and Axios


