Skip to content

GitHub Pages Deployment: Free Static Website Hosting ​

💡 One-sentence summary: create a username.github.io repository, paste the AI-generated files into it on the web page, open Pages in Settings—after at most 10 minutes, your website is on the public internet.

Search for "GitHub Pages tutorial" and most of the top articles assume you already know Git: clone, push, SSH keys at full speed—beginners quit after two paragraphs. This lesson cuts all of that out—in Lesson A1, the AI already wrote index.html, style.css, and script.js into your folder; now only the final step of "handing the folder over to GitHub" remains, done entirely by clicking through in the browser.

This is Lesson 2 of Route A (building websites) in Scenario Hands-On: A1 handles "building it," and this lesson handles "putting it online"; A3 and A4 are the same task done on two other platforms.

What You'll Be Able to Do After This Lesson ​

  • Create a repository with a strictly formatted name <你的用户名>.github.io so GitHub recognizes it as "your personal site"
  • Without installing Git or touching the command line, put the AI-generated web files into the repository via the browser
  • Configure the publishing source in Settings → Pages to turn the repository into a website accessible on the public internet
  • Explain why you wait at most 10 minutes after a change, and where to look for the cause if it exceeds 1 hour
  • From now on, every time you update files, the website is automatically republished—no need to re-upload the whole site

Your Current Situation ​

  • "The page has been sitting in a folder for a week. I know I need to 'deploy,' but every search turns up git commands and SSH keys—I can't understand them and don't dare try"
  • "I heard going online means buying a server, tens of yuan a month—totally not worth it for a personal homepage"
  • "I registered on GitHub but only know how to click Star—I created a repository once and never opened it again"

When to Use This Approach ​

When you need:

  • A free, stable public URL to send the AI-built page directly to others
  • To conveniently own your first GitHub repository—useful for portfolios and storing files
  • Every future change to be automatically republished, without manually re-uploading

And you don't want to:

  • Install Git, configure SSH, or learn the command line
  • Spend money on a server or a domain (use the username.github.io URL GitHub gives you for now)
  • Study a pile of incomprehensible configuration options in a cloud platform console

Prefer "drag a folder and go live"? That's A3 Cloudflare Pages; prefer "one command to go live"? That's A4 Vercel. For a comparison of the three platforms' free tiers, see A5 Deployment Platform Comparison.

🎒 Preparation Before Starting ​

  • Complete A1 Build a Website with AI: your folder contains a verified index.html, and ideally also style.css and script.js
  • A GitHub account (if you don't have one yet, register first on the GitHub official website)
  • Know your GitHub username—the repository name is built from it, and even if it contains uppercase letters, it must be converted entirely to lowercase
  • Be clear that the repository must be public: for GitHub free accounts, the Pages repository must be Public—see item 4 in "Pitfall Warnings" for what this means

Core Idea ​

GitHub Pages is GitHub's official static website hosting service: it takes HTML, CSS, and JavaScript files directly from your repository and publishes them as a website. You don't need to buy a server—building and publishing are done automatically by GitHub's Actions workflow, free with standard build machines for public repositories.

The whole mechanism has only three roles:

RoleWhat it isValue in this lesson
RepositoryWhere the website files are stored<你的用户名>.github.io
Publishing sourceWhich branch and directory the files are taken from for publishingRoot directory of the main branch /
Entry fileThe first file visitors see when they open the URLindex.html

One pipeline: put files into the repository → specify the publishing source in Settings → Pages → GitHub builds automatically (when publishing from a branch it uses the Jekyll builder by default, which you don't need to worry about) → visitors open https://<你的用户名>.github.io. After that, every time you commit a change, this pipeline reruns automatically.

Why must the repository name be 用户名.github.io? Because GitHub Pages has two kinds of sites, and user sites are identified by the repository name:

Site typeRepository nameURLQuantity limit
User site (this lesson)<用户名>.github.iohttps://<用户名>.github.io1 per account
Project siteAny repository namehttps://<用户名>.github.io/<仓库名>1 per repository

Finally, remember the boundary: GitHub Pages only publishes static files and does not support server-side languages like PHP, Ruby, or Python—that's exactly why Lesson A1 had you make your first version a purely static page. If you truly need dynamic features, see A5 deployment platform comparison.

Follow along ​

After five steps, your folder becomes a public web address. Everything is done by clicking in the browser—you don't have to type a single command.

Step 1: Create a repository named username.github.io ​

Why: The repository name for a user site is a strict requirement—GitHub uses this name to recognize "this is someone's personal site." Misspell a single letter, and it's just an ordinary repository.

  1. Log in to GitHub, click + in the top right corner, and choose New repository
  2. Enter <你的用户名>.github.io as the repository name. For example, if the username is octocat, the repository name is octocat.github.io; if the username contains uppercase letters, convert them all to lowercase
  3. Choose Public for visibility—Pages repositories on GitHub free accounts must be public
  4. Toggle the Add README switch to On so the repository has a file to start with
  5. Click Create repository

You should see: an empty repository page with a README.md sitting in the file list.

  • The repository name matches your username exactly, all lowercase

Step 2: Put the AI-generated website files into the repository ​

Why: GitHub Pages only publishes the files in the repository. Right now your website is still in a folder on your own computer, so it has to be moved in—and you can move it without installing Git: create files on the web page and paste in the code.

  1. Create a new file in the repository page's file list and name it index.html
  2. Open the index.html that AI generated in Lesson A1 with a text editor, select all, copy, and paste it into the editor box on the web page
  3. Click Commit changes to commit
  4. For style.css, script.js, and the other page files, create, paste, and commit them one by one the same way

You should see: index.html, style.css, and script.js appear in the repository file list, matching the inventory in the Lesson A1 folder.

💡 The rules for entry files

GitHub Pages' list for finding the entry file is index.html, index.md, README.md (the official documentation lists them in exactly this order). Your index.html must be placed at the outermost level of the publishing directory—this lesson's publishing source is the repository root, so put it in the repository root, not inside any subfolder. The README.md that was auto-generated when the repository was created can stay; it will continue to serve as the repository's readme front page.

⚠️ Images can't be pasted in

index.html and style.css are text and can be pasted; binary files like photos cannot. For the first version, have AI change the placeholder images to inline SVG or pure CSS effects (both are text and can be pasted just the same); uploading real images is not covered in this lesson.

  • The repository root has index.html, with not a single letter of the filename misspelled

Step 3: In Settings → Pages, choose the publishing branch ​

Why: Once the files are in place, one "switch" remains—telling GitHub which branch to take the files from for publishing. The official term for this is configuring the publishing source.

  1. Under the repository name, click Settings
  2. In the left sidebar, inside the Code, planning, and automation group, click Pages
  3. In the "Build and deployment" area, under Source, select Deploy from a branch from the dropdown
  4. Under Branch, select main from the dropdown, and select / (root) for the directory next to it—your files are in the repository root
  5. Click Save

You should see: Source shows Deploy from a branch and Branch shows main. GitHub then starts the first build—you don't have to do anything, just wait.

  • Source = Deploy from a branch, Branch = main + / (root), Save clicked

Step 4: Wait up to 10 minutes, then visit your new website ​

Why: GitHub builds and publishes your site in the background using an Actions workflow. Per the official wording: after pushing changes, it can take up to 10 minutes to take effect—this is the normal pace, not something stuck.

  1. Within 10 minutes, open https://<你的用户名>.github.io in your browser
  2. You can also go straight there from the repository's Settings → Pages page by clicking Visit site

You should see: the very page you verified in Lesson A1 appears on the public web as-is. Send the link to a friend—they can open it without ever touching your computer.

Still can't open it after 10 minutes? First double-check the URL spelling (it's the repository name), then wait a bit longer; if it still hasn't updated after more than 1 hour, go to the repository's Actions tab to check the workflow run records—build errors are all left there. See item 3 of the "pitfall reminders" for details.

  • https://<你的用户名>.github.io opens and shows your index.html

Step 5: Update the website—the everyday loop of the GitHub Pages tutorial ​

Why: Going live isn't a one-time deal. Every future content change follows the same loop, and it's even easier than the first time.

  1. Have AI revise the files; for small changes you can also click the pencil icon on the web page to edit directly
  2. Commit the changes (Commit changes)
  3. Wait up to 10 minutes, then refresh the URL

You should see: the URL stays the same, and the content updates automatically within 10 minutes.

💡 To commit is to publish

Every change you push to the publishing branch makes GitHub Pages automatically republish—per the official documentation: as long as changes are pushed to the source branch, changes in the source folder are published to the site. There is no "go live again" button to press.

Checkpoint ✅ ​

  • The repository name must be exactly <你的用户名>.github.io, all lowercase
  • index.html is in the repository root (the outermost level of the publish directory), not in any subfolder
  • Settings → Pages:Source = Deploy from a branch,Branch = main + / (root)
  • https://<你的用户名>.github.io opens and shows your page
  • Remember two numbers: wait at most 10 minutes after making changes; if it takes more than 1 hour, go to Actions to check the workflow records

Pitfall Reminders ​

❌ Repository name misspelled, or uppercase not converted to lowercase ​

Symptom: https://<用户名>.github.io won't open, even though the repository was clearly created.

Cause: The user site's repository name is a hard rule—GitHub only accepts <用户名>.github.io as the one valid format; if your username contains uppercase letters, the repository name must still be all lowercase.

Correct approach: Check the spelling of your username against your GitHub profile page, recreate the repository as <用户名>.github.io in all lowercase, and re-paste the files—it's just a few files, a few minutes of work.

❌ index.html was placed inside a subfolder ​

Symptom: The URL opens, but what you see is the content of README.md, not the page you built.

Cause: The entry file must be at the outermost level of the publish directory. AI sometimes generates the whole set of files inside a subfolder like site/, and if you copy it over as-is, index.html ends up buried one level deeper, leaving only README.md in the root directory eligible as the entry.

Correct approach: In this lesson the publish source is the repository root /; index.html, style.css, and script.js all go directly in the root directory; relative references between files (like href="style.css") work as-is—the site's directory structure matches the repository.

❌ No update after ten minutes, so you keep changing settings ​

Symptom: You committed changes, but refreshing still shows the old page, so you keep tweaking Settings back and forth and re-uploading deleted files.

Cause: The official docs clearly state that after pushing you may need to wait up to 10 minutes. Building takes time; it isn't a failure.

Correct approach: Wait the full 10 minutes before judging. Only if it hasn't updated after more than 1 hour do you need to investigate: go to the repository's Actions tab to see whether the latest workflow run succeeded or errored; then confirm that the person who pushed has repository admin permissions and that their GitHub account has a verified email—the official docs say builds won't be triggered if either of these conditions isn't met.

❌ Putting content you don't want public into the repository ​

Symptom: Phone numbers, ID photos, and various keys got committed along with the website files.

Cause: Pages repositories on free GitHub accounts must be Public; moreover, the official docs specifically warn that even if the repository is private (only allowed on paid plans), the Pages site's content is still publicly visible on the web. "Private repository = nobody can see it" does not hold on GitHub Pages.

Correct approach: Go through the file checklist before going live—remove sensitive data first, then publish. The official warning's recommendation is exactly this: remove sensitive data before publishing. If you mind the content being public, see A5 Deployment Platform Comparison for platform considerations.

Advanced Tips (Optional) ​

🚀 Want to use a framework like VitePress? (Optional) ​

When publishing from a branch, GitHub Pages builds your files with Jekyll by default. To switch to another static site generator, the official docs offer two paths: use a GitHub Actions workflow to build and publish instead (official templates are provided; the general flow is pull code → build → upload artifact → deploy), or place an empty file .nojekyll in the publish source root to turn off Jekyll. For your first site, get the full workflow running with the hand-written static files from A1, and leave frameworks until after A5.

🚀 Want a dedicated page for each work? (Optional) ​

An account has only one user site, but project sites are one per repository: open Settings → Pages in any repository and do the same configuration, and the URL is https://<用户名>.github.io/<仓库名>. One link per project in your portfolio—that's how it's done.

🚀 Want to switch to your own domain? (Optional) ​

username.github.io Stick with it for now. Once you have your own domain, the full process from DNS setup to binding is in 5.3 Custom Domain.

Lesson Summary ​

✅ You've completed the full deployment workflow of this GitHub Pages tutorial:

  • Create the repository: the name must be exactly <用户名>.github.io, choose Public on a free account
  • Move the files: create files on the web page and paste the code, with index.html in the repository root
  • Enable publishing: Settings → Pages, Deploy from a branch + main + / (root)
  • Verify: wait at most 10 minutes, then https://<用户名>.github.io opens and shows your page
  • Update: edit files → Commit changes → automatic republication within 10 minutes
Key ConfigurationRecommended ValueDescription
Repository name<用户名>.github.ioThe dedicated name for user sites, all lowercase
VisibilityPublicA hard requirement for free GitHub accounts
SourceDeploy from a branchThe web wizard route; the other option is GitHub Actions
Branch / directorymain + / (root)Publish from wherever the files are
Entry fileindex.htmlindex.md or README.md also works; must be at the outermost level of the publish directory
Time to take effectAt most 10 minutesIf it takes more than 1 hour, check the workflow records in Actions

Next Lesson Preview ​

In the next lesson, A3 Going Live on Cloudflare Pages: no repository needed—just drag a folder in your browser and you're live. You'll learn:

  • How Direct Upload drag-and-drop gets you a 项目名.pages.dev URL in three steps
  • How people who know Git can use Git integration to achieve "automatic deployment on every push"
  • Why these two deployment methods can't be swapped once chosen
  • What Cloudflare's official recommendation that new projects start with Workers means for beginners

When you're ready, keep the folder at hand and head into A3 →

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.