Dinesh Pandiyan

Posted on Jan 23, 2019 • Updated on Jan 26, 2019

Deploy Gatsby sites to GitHub Pages

#webdev #javascript #gatsby #react

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.

Personal Website - Repo name should be username.github.io and the site can be accessed at https://username.github.io
Project Website - Repo name can be anything and the site can be accessed at https://username.github.io/repo-name

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.

Steps

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
ghpages.publish(
  'public',
  {
    branch: 'master',
    repo: 'https://github.com/flexdinesh/flexdinesh.github.io.git',
  },
  () => {
    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 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)

doug • Aug 14 '19

Thanks for this article. Really helpful. ...one issue i'm having is that in order to have the URL of my github pages site be [username].github.io instead of [username].github.io/repo-name 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 github.com/flexdinesh/portfolio clean while still using github pages?

JT McHorse • Oct 16 '19

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

Nitish Kumar Singh • Mar 10 '19

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 ?

Dinesh Pandiyan • Mar 11 '19

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

Nitish Kumar Singh • Mar 11 '19

How GitHub pages works ?
I mean from which branch.

Dinesh Pandiyan • Mar 12 '19

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

Lenny Martinez • Oct 9 '19 • 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?)

Dinesh Pandiyan • Oct 9 '19

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.

Paramanantham Harrison • Jan 23 '19

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?

Dinesh Pandiyan • Jan 23 '19

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.

Paramanantham Harrison • Jan 23 '19

Got it

Ananya Verma • Aug 15 '20 • 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 • Feb 1 '19

I use gatsby+TravisCI+firebase for my deployment.

Jakob Attkinson • Jun 6 '20

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?

Hannah Werman • Feb 10 '19

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 Simard-Quesnel • Mar 22 '19

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

Anand Amrit Raj • Jan 24 '19

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.

dev.to/anamritraj/how-to-create-a-...

yogeshwaran • Aug 21 '19

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 ?