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 username.github.io and the site can be accessed at https://username.github.io
2. 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! 🔥

Comments

[doug]

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]

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]

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]

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

[Nitish Kumar Singh]

How GitHub pages works ?
I mean from which branch.

[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.

[Lenny Martinez]

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]

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]

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]

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]

Got it

[Ananya Verma]

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]

I use gatsby+TravisCI+firebase for my deployment.

[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?

[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 Simard-Quesnel]

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