Deploy Gatsby sites to GitHub Pages

Jan 23, 2019

This article is also cross-posted in —

DEV - Deploy Gatsby sites to GitHub Pages

codeburst - Deploy Gatsby sites to GitHub Pages

Gatsby is all the rage now, thanks to the amazing team behind the fancy and easy-to-use framework. I'm not going to go into the details of why you should use Gatsby if you're building a static website. There are a ton of posts out there that say just that.

Here's an excellent article on why - Why you should use GatsbyJS to build static sites

These are my top reasons

  • Amazing Dev Experience
  • Pre-baked optimizations
  • Generated site is super fast
  • Out of the box support for GraphQL

Deploy Gatsby sites anywhere

Since Gatsby generates static files, you can deploy it anywhere. But the easiest and quickest option would be to deploy your site to GitHub Pages.

GitHub Pages

You can host static websites for free with GitHub Pages. You can have two types of websites hosted in GitHub Pages.

  1. Personal Website - Repo name should be and the site can be accessed at
  2. Project Website - Repo name can be anything and the site can be accessed at

All you gotta do is to push the static site to the repo with index.html at the root dir.

More info here - GitHub Pages

Deploy Gatsby sites to GitHub Pages

Gatsby generates your static site when you run the command gatsby build.

Only catch here is that GitHub Pages expect your site files to be in the root dir but Gatsby generates the site files in a dir called public. So we cannot host the source code and the public files in the same repo.

gh-pages is a really nice package that helps you push static sites to a GitHub repo from anywhere.


  • yarn add gh-pages --dev
  • Create a new dir scripts at project root and create a file deploy-github.js in scripts dir
  • Add this code to deploy-github.js
const ghpages = require('gh-pages')

// replace with your repo url
    branch: 'master',
    repo: '',
  () => {
    console.log('Deploy Complete!')
  • Add a new npm script deploy:github in package.json
"deploy:github": "npm run build && node ./scripts/deploy-github"
  • Run the script and your static site will be up and running in a few seconds

Note: When you run the command, you will be asked to enter your GitHub creds in the command line before publish.

If you need further materials, you could take a look at the source code of my personal website Dinesh Pandiyan - Portfolio. It is deployed in both Netlify and Github Pages.

If you're looking for a good Gatsby starter template, I maintain a boilerplate with my pre-baked web setup - Gatsby Boilerplate. I usually fork this repo if I want to start with a new Gatsby site.

Happy Gatsbying! 🔥