Web Development
Updated 28 days ago | GitHub

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 to initialize git on that repository.

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 default branch is still called master, push to master instead. You can rename it to main later in Settings → Branches.

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 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. The first publish can take up to 10 minutes; subsequent pushes deploy faster.

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.