Deploying Gatsby to GitHub Pages

Sometimes you just want a simple hosting solution. For Gatsby projects I have been using Gatsby Cloud for builds and pushing to Netlify for hosting. It works well. However, I recently built a couple personal projects with Gatsby that don't need a cloud pipeline and decided to use GitHub pages to host. What follows is everything I had to do to get that working with a project directory as well as with a personal subdomain.

Setting up GitHub to Receive Your Built Files

• First, create a branch in your project named gh-pages and push it to your repo.

• Next, go to your repo on GitHub and click on "Settings", then "Options" and scroll down to the Pages section:

• In the source drop-down menu, select your gh-pages branch:

• This will set up the website to deploy from the gh-pages branch to a project directory off your GitHub user domain. For me, the default is arnonate.github.io/<project-name>/.

Setting up Gatsby to Deploy to GitHub

There are a few changes you will need make in your Gatbsy project in order to resolve this directory url:

• Install the gh-pages package:

yarn add gh-pages -D

• In your gatsby-config.js, add the following line (which should match the project directory created in step 4 above):

module.exports = {
  pathPrefix: `/<project-name>`,
}

• Add a deploy script to your package.json:

"scripts": {
  "deploy:github": "gatsby build --prefix-paths && gh-pages -d public",

• Run the deploy! Note: If you ever change the pathPrefix setting be sure to run gatsby clean before the next deploy to clear the build cache.

Deploying to an Apex or Subdomain

If you don't want to prefix your pages/assets paths and would rather push to the root directory of an Apex or Subdomain, there are a couple extra steps:

• Remove the prefixPaths setting in your gatsby-config.js:

module.exports = {
  pathPrefix: `/<project-name>`, // Delete this line
}

• If you have already deployed with this setting, make sure you run gatsby-clean to clear the build cache.

• Remove --prefix-paths from your deploy script:
  

"scripts": {
  "deploy:github": "gatsby build && gh-pages -d public",
}

• In your project settings on GitHub, enter your custom domain name or subdomain:

• Add/change records for your domain at your domain provider. Specifically, if you are using a subdomain, then add a CNAME that points to your root domain on GitHub (username.github.io). If you are using an apex domain, then you need to point an A record or an ALIAS to GitHub Pages:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

• Add a CNAME file in the static/ directory of your Gatsby project with your custom domain address:

my-domain-name.com

For an example of a CNAME file, check out my Gatsby/Wordpress starter repo. Check out the full project if you want a starting point for Gatsby, WordPress, TypeScript and Jest!