Deploying a Gatsby site to GitHub Pages from Travis CI

I recently worked on a simple static website for an open source project I have and took Gatsby for a spin along with one of the theme starters. To serve the web pages, I decided to host my Gatsby generated static website on GitHub pages where I also host the source code, so that everything is nicely tied together.

With GitHub Pages, there are two options to host and serve the website:

1.  a dedicated branch named gh-pages.

2. use another branch, for example, master, and put all the website code in a docs/ directory.

For my project, I chose to make use of the latter and put all the website’s source code in the master branch docs/ directory and then deploy to gh-pages.

Deploying to GitHub pages

Gatsby generates the code of the static website in the directory public/, which needs to be pushed to GitHub pages to be served. To push the code to the remote repository from a Travis CI and work all the git magic, we use the npm module gh-pages.

You also have the option to install the gh-pages module to test and deploy from your local development environment but it’s not mandatory.

Step 1: obtain a GitHub token

To push changes from the CI system, in our case Travis CI, to GitHub pages, you need to authenticate. A recommended way for doing this is using GitHub developer tokens and not providing your own account username and password.

In GitHub, go to your account settings -> Developer settings -> Personal access tokens, and create a new token that provides therepo access permissions.

In the Travis configuration, for the repository add a new secret environment variable of the name GH_TOKEN with the value of the token obtained from GitHub. Make sure youDO NOT toggle thedisplay in build logs setting as the token is best to remain secret. Otherwise, others are able to push to your repository.

Step 2: deploy run script

Update the Gatsby project's package.json to also include a deploy run script which invokes gh-pages with two important command arguments:

1. -d public - specifies the directory in which the built files exist and will be pushed as a source to GitHub pages

2. -r URL - the GitHub repository URL, including the use of a GitHub token to be able to push changes to the gh-pages branch, in the form of https://$GH_TOKEN@github.com/<github username>/<github repository name>.git

Here's an example:

"scripts": {
  "deploy": "gatsby build --prefix-paths && gh-pages -d public -r https://$GH_TOKEN@github.com/lirantal/dockly.git"
}

Step 3: update .travis.yml

The following .travis.yml configuration provides a reference:

language: node_js
before_script:
  - npm install -g gatsby
node_js:
  - "10"
deploy:
  provider: script
  script: cd docs/ && yarn install && yarn run deploy
  skip_cleanup: true
  on:
    branch: master

Let’s break down the important bits for deploying the Gatsby website from Travis to GitHub pages:

1. before_script is used to install the Gatsby CLI so that the gatsby command can be used in the project's run script to build the Gatsby website.

2. deploy fires only when the build runs on the master branch, in which case, it fires off the script. The script here is a set of instructions to deploy the Gatsby site located in the docs/ directory. In this directory, it needs to install all the website dependencies and run the deploy script, as was set in the previous step.

Summary

Following this tutorial, you are now ready to get your website out to the world and share it with us!

If you’re using CircleCI or others, the workflow and general guidelines are almost identical, with the exception of the specifics around CircleCI’s deployment file and environment variables settings. In the spirit of open source, I contributed a documentation Pull Request to the official Gatsby repository that documents this whole process, so future users of Gatsby have an easier way to get by!