Deployment with GitHub Pages

When you want to put your website on the internet for the world to see, you’ll need to deploy it. There are many services to do this, and there is a whole career (devOps) dedicated to deployment and maintenance of websites and apps. To keep it simple though, we’re going to use GitHub Pages, which lets you publish a static site directly from any branch in a GitHub repository.

💡 You used to need a branch literally named gh-pages for this to work, but GitHub Pages now lets you pick any branch (commonly main) and a folder (/ or /docs) as the publishing source in Settings → Pages. See the GitHub Pages quickstart and Configuring a publishing source.

Instructions

Step 1: Create a GitHub repository for your site.

Go to GitHub and click on the ‘+’ button on the top right of the screen. Select ‘New Repository’, and follow the next instructions by giving it a name.

Copy the commands to add the remote origin.

Step 2: Initialize git inside your project directory and connect to GitHub

In your command line, navigate to the folder with your project files. Type git init -b main to initialize git on that repository with the initial branch named main — the same command GitHub’s guide to adding locally hosted code uses (it requires Git 2.28 or later; on older Git, run git init and then git symbolic-ref HEAD refs/heads/main).

Paste in the git remote add origin .... line to connect to GitHub.

Step 3: Commit your changes

$ git add .
$ git commit -m "Preparing website for deploy."

Step 4: Push your changes to GitHub

$ git push -u origin main

If your local branch is still called master (for example, because the repository was initialized with a plain git init on an older Git), rename it before pushing with git branch -m master main. Alternatively, push to master instead and rename the branch on GitHub afterwards — renaming on GitHub does not update your local clone, so then run the commands from that guide to rename the local branch and point it at the renamed remote branch: git branch -m master main, git fetch origin, git branch -u origin/main main, and git remote set-head origin -a.

Step 5: Enable GitHub Pages in repository Settings

This step is what actually publishes the site — without it, pushing the code is not enough.

1. On GitHub, open your repository and click Settings.
2. In the left sidebar, click Pages (under “Code, planning, and automation”).
3. Under Build and deployment, set Source to Deploy from a branch.
4. Under Branch, choose the branch you just pushed (e.g. main) and the folder (/ (root) for a plain HTML/CSS/JS site, or /docs if your files live in a docs/ subdirectory).
5. Click Save.

GitHub will build and deploy the site. It can take up to 10 minutes for changes to your site to publish after you push them to GitHub.

Step 6: Enjoy your website!

Once Pages reports a successful deployment, visit:

https://<your-github-username>.github.io/<repository-name>/

Note: Make sure you have an index.html file at the root of your publishing source, or you’ll see a 404.