How to Upload HTML to GitHub: Web UI and Git CLI, Then Publish

Q: Can I upload a whole folder to GitHub without using git?

Not directly by dragging a folder in most browsers -- GitHub's web upload expects individual files. Select all the files inside the folder (including subfolders' files dragged separately) or switch to the git CLI, which handles nested folder structures natively with git add .

You can upload HTML to GitHub two ways: drag files into the browser with Add file > Upload files, or push them with the git command line. The browser method is faster for a one-off site; git is the right habit once you will touch the files again.

Getting HTML files into a GitHub repository is the easy part. The part people actually get stuck on is what happens after — naming the file correctly and choosing how the site actually gets served to a browser. This tutorial covers both upload methods end to end, then the two realistic ways to publish once the files are there.

Method 1: the web UI, drag-and-drop
Method 2: the git CLI, from init to push
Naming the file index.html
Publishing option 1: GitHub Pages
Publishing option 2: connect the repo to an auto-deploying host
Updating the site after the first upload
How this fits the rest of the stack
FAQ

Method 1: the web UI, drag-and-drop

Open the repository on github.com, click Add file, then Upload files. Drag your HTML, CSS, and JavaScript files onto the page, or click to browse for them, then write a commit message and click Commit changes.

This method has real limits worth knowing before you rely on it: up to 100 files per upload, and 25MB per individual file through the web interface. A small static site clears both easily; a site with a large images folder or a bundled video will not, and you will need the git CLI or Git LFS instead.

No local git installation required — works entirely in the browser
Fastest path for a single index.html plus a stylesheet
Cannot upload an entire folder structure by dragging a folder in most browsers — select the files inside it instead, or use git
Each upload session is one commit, so batch related files together

If you are starting from a brand-new empty repository, GitHub shows the Upload files option directly on the repository’s empty-state page, so you never need to create a placeholder README first.

Method 2: the git CLI, from init to push

The command-line path scales better and is worth learning even for a single HTML file, because it is the same workflow you will use for every project after this one.

# from inside your project folder
git init
git add .
git commit -m "Initial commit"

# create the repo on GitHub first, then connect it
git remote add origin https://github.com/your-username/your-repo.git
git branch -M main
git push -u origin main

git init creates a local repository in the current folder. git add . stages every file in it. git commit records that snapshot with a message. git remote add origin points your local repository at the empty one you created on GitHub. git branch -M main makes sure your default branch is named main, matching what GitHub expects. git push -u origin main sends the commit up and links the branches together, so future pushes are just git push.

The one-time setup cost of git pays off the moment you need to update a file, roll back a bad change, or see a history of what you changed and when — none of which the web upload gives you.

If git push fails with an authentication error, it is almost always because GitHub stopped accepting account passwords for git operations years ago. You need either a personal access token used in place of a password, or an SSH key added to your GitHub account and a remote URL that starts with [email protected]: instead of https://github.com/. Both are one-time setup steps, and either works fine for a static HTML project.

A second common snag: git push -u origin main fails with “repository not found” when the remote URL has a typo, or with “failed to push some refs” when the GitHub repository was created with an initial README and already has a commit your local repository does not know about. The fix for the second case is git pull origin main --allow-unrelated-histories before pushing again, or simply create the GitHub repository empty in the first place to avoid the conflict entirely.

Naming the file index.html

Whichever method you use, the entry-point file must be named exactly index.html, lowercase, at the root of whichever folder you plan to publish from. This is not a GitHub-specific rule — it is how every static web server decides what to serve when a visitor requests a bare URL with no filename — but GitHub Pages enforces it strictly.

A repository with Index.html (capital I) or home.html instead of index.html will upload fine and then serve a 404 the moment someone visits the site’s root URL. This is the single most common reason a freshly uploaded site “does not work” on the first try.

Publishing option 1: GitHub Pages

Once the files are in the repository, go to Settings > Pages, choose the branch to serve from (usually main), and the root folder or /docs if your site lives in a docs subfolder. Save, wait a few minutes, and the site is live at https://your-username.github.io/your-repo/.

For a full walkthrough of the settings, custom domains, and the build status indicators, see the dedicated guide: Getting Started with GitHub Pages.

Publishing option 2: connect the repo to an auto-deploying host

GitHub Pages is free and simple, but it is a static file server with no build pipeline of its own — fine for plain HTML, limiting the moment you want a build step, custom response headers, redirects, or a preview URL per pull request.

The alternative is connecting the same repository to a host that watches it and deploys automatically on every push. On RunxBuild, pointing a static site at a GitHub repository gets you a build log, a live route, custom domains, and 120GB of bandwidth included before usage-based billing kicks in — without changing anything about how you got the files into GitHub in the first place.

The upload method does not change based on where you publish. Everything in the first two sections applies whether the destination is GitHub Pages or a connected host.

Updating the site after the first upload

For the web UI method, navigate to the file in the repository, click the pencil icon to edit it directly in the browser, then commit the change — no re-upload needed for small edits.

For the git method, edit the files locally, then run the same three commands you will use forever:

git add .
git commit -m "Update homepage copy"
git push

Both GitHub Pages and a connected auto-deploy host pick up the new commit and redeploy automatically — that redeploy-on-push behavior is the actual value of connecting a repository instead of uploading a folder somewhere once and forgetting about it.

It is worth deciding early which update method you will actually use day to day, because mixing both on the same repository gets confusing fast: editing a file in the browser while a local clone also has uncommitted changes to the same file is how people lose work to a merge conflict on their very first project. Pick one primary method and treat the other as an occasional convenience, not a parallel workflow.

How this fits the rest of the stack

Getting a folder of HTML files onto GitHub takes minutes either way. What decides how much you enjoy maintaining the site afterward is whether updates are a redeploy or a re-upload, and whether you outgrow a plain file server before the project does. The RunxBuild hosting calculator is a fast way to see what a connected, auto-deploying static site actually costs once bandwidth and a custom domain are in the picture.

Useful related references:

FAQ

Can I upload a whole folder to GitHub without using git?

Not directly by dragging a folder in most browsers — GitHub’s web upload expects individual files. Select all the files inside the folder (including subfolders’ files dragged separately) or switch to the git CLI, which handles nested folder structures natively with git add .

What is the file size limit for GitHub’s web upload?

25MB per file through the drag-and-drop web interface, and up to 100 files per upload batch. Larger files need the git CLI, and files over 100MB need Git LFS regardless of method.

Does the file have to be named index.html?

Yes, if you want it served automatically at your site’s root URL. Static web servers, including GitHub Pages, look for index.html by default when a visitor requests a folder with no specific filename.

How long does GitHub Pages take to publish after I upload files?

Usually one to a few minutes. Check Settings > Pages for a build status indicator, or the Actions tab if Pages is building via a workflow rather than the legacy branch-based deployment.

Do I need a GitHub account to upload HTML files this way?

Yes, both methods require a GitHub account and a repository you have write access to. Creating an account and a repository is free and takes under a minute before either upload method applies.