DEV Community

Dinesh Pandiyan
Dinesh Pandiyan

Posted on • Updated on

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!')
Enter fullscreen mode Exit fullscreen mode
  • Add a new npm script deploy:github in package.json
"deploy:github": "npm run build && node ./scripts/deploy-github"
Enter fullscreen mode Exit fullscreen mode
  • 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 to 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! πŸ”₯

Top comments (19)

afxjzs profile image

Thanks for this article. Really helpful. issue i'm having is that in order to have the URL of my github pages site be [username] instead of [username] i need to push to my master branch, but when I run the deploy script, it adds all the compiled/built code to master. How do you keep the master branch at clean while still using github pages?

jtmchorse profile image
JT McHorse

Hi Diniesh, this post was exceedingly helpful. It took me all of half an hour to get gatsby running locally and setup to deploy by following your guide and using the quick start example from gatsby.

One thing that might be helpful to show is how to run npm scripts, despite using Gulp every day I wasn't sure how to run an npm script and had to go find it on StackOverflow.

npm run-script deploy:github

nitishk72 profile image
Nitish Kumar Singh

What is the setting of your netlify.

As I have seen you have to branch dev and master. Netlify have ability yo pull a branch and build it and then deploy.

My question is that

which branch you are using on Netlify and with what settings ?

flexdinesh profile image
Dinesh Pandiyan

The source code is in this repo. Netlify deploys automatically everytime I push to master.

nitishk72 profile image
Nitish Kumar Singh

How GitHub pages works ?
I mean from which branch.

Thread Thread
flexdinesh profile image
Dinesh Pandiyan

I have a script deploy:github that deploys the code to github pages. I do it manually every time I make a change.

lennymartinezd profile image
Lenny Martinez • Edited

Is there a particular reason why you use a script to push things?
Does the typical git flow of add>commit>push not have an effect on a GatsbyJS app? I'm coming from Jekyll to Gatsby and trying to understand how to setup a repo for this all to work (should I be using netlify to host things?)

flexdinesh profile image
Dinesh Pandiyan

Re: script

You don't have to use an npm script to do things. You can do it with git commands. npm script is an automation to make things faster.

Re: netlify

GitHub Pages is completely free but has limitations if the traffic bandwidth becomes really really high.
Netlify has a free tier but has limitation on the build minutes in the free tier.

You can choose either of these or a different static hosting service to deploy your site. It's upto you.

learnwithparam profile image
Paramanantham Harrison

Doesn’t it require authentication for the repo or it will handle repo only if the repo is under same user name?
How it works without the need for authentication?

flexdinesh profile image
Dinesh Pandiyan

When you run the command, it will ask for authentication in the command line.

I'll edit the post and add it as a note.

learnwithparam profile image
Paramanantham Harrison

Got it

vermaananya profile image
Ananya Verma • Edited

Thanks for the article. Although my website is running properly, but I'm facing one issue while deployment. My gatsby project file structures and the files are getting changed while deploying (when npm run-script deploy:github ) command is run. Although the files remain intact before running the deploy-command.

Let me know where I'm doing it wrong.

niyasrahman profile image

I use gatsby+TravisCI+firebase for my deployment.

attkinsonjakob profile image
Jakob Attkinson

If our gatsby project uses some private api-key / passwords, how would we deploy an app and secure these private keys? Using the .env file is not secure, since these stored on the client-server. Such a problem would require, I imagine, a server-side solution thus deploying might be a bit more complicated?

hanna2895 profile image
Hannah Werman

Thanks for writing such an informative article! I added the code into my project and it runs the build, but then it just gets stuck (no prompt for authentication, success, or error message). How do I tell if it's working, or figure out what's going wrong?

eloi profile image
Eloi Simard-Quesnel

I typed "gatsby github pages" on google and this came up instantly. Thank you, it was exactly what I needed!

anamritraj profile image
Anand Amrit Raj

Not to promote my article or anything. I just want to add to what Dinesh is conveying here.

You can also integrate TravisCI to automatically deploy it to gh-pages. All you have to do is push changes to master.

yogeshktm profile image

Hey dinesh. i have setup deployed in netlify. I need to add my custom domain for the netlify site. Changed DNS settings and namespace. It didn't work yet. any idea ?

hebasaadosman profile image

thanks for your useful article ,
i publish my site but it redirect to default gatsby site
how i make it redirect to index.html