How To Deploy Gatsby to GitHub Pages With gh-pages and GitHub Actions

• Initial Context
  • Setting up GitHub Actions secret
  • Installing npm packages
• Setup Deployment
  • Making the deploy script
  • Setting up the GitHub Actions workflow
• Conclusion
• Additional Resources

This tutorial will show you how to use gh-pages and GitHub Actions to automatically deploy a Gatsby project to Github Pages repo. These steps and scripts are currently in use on this site.

Initial Context

This guide assumes there are two git repos, one to house the Gatsby project code and one for the Github Pages public files. Each git repo will have these characteristics:

• Gatsby project repo
  • static site generator source files
  • deploy script via package.json
  • GitHub Actions workflow yaml file
• GitHub Pages repo
  • files in repo were generated via Gatsby project
  • public web root for GitHub Pages
    • https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site
  • NOTE: For this tutorial, the git repo https://github.com/username/username.github.io.git is assumed

Setting up GitHub Actions secret

In order to transfer files from one GitHub repo to another, the GitHub Actions need an authentication token to commit to the correct repo; this is achieved via personal access tokens. Follow these steps to setup a secret for the personal access token.

• Create the personal access token
  • https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
  • NOTE: Token only needs repo access (read/write)
• For the Gatsby project repo, store personal access token as a GitHub Actions secret
  • https://docs.github.com/en/actions/security-guides/encrypted-secrets
  • NOTE: In this tutorial, PERSONAL_ACCESS_TOKEN is used as the key

This secret will be used in both the deploy script and in the GitHub Actions workflow.

Installing npm packages

For the deploy script, two npm packages will be needed:

• Install Gatsby CLI globally
  • NOTE: Most Gatsby projects may already have this installed globally.
  • Run npm install -g gatsby-cli
• For the Gatsby project repo, install gh-pages locally
  • Run npm install --save-dev gh-pages

Setup Deployment

Now for the fun part! The next two scripts will work in tandem to deploy the Gatsby project to the Github Pages repo.

Making the deploy script

Add this npm script to the Gatsby project’s project.json.

"scripts": {
  ...
  "deploy": "gatsby build && gh-pages -d public -b main -r https://$PERSONAL_ACCESS_TOKEN@github.com/username/username.github.io.git"
}

• gatsby build will build the Gatsby site into the public directory
• gh-pages will deploy the site with these flag arguments
  • -d public is the directory name which is getting deployed
  • -b main is the branch name of the destination repo
  • -r https://$PERSONAL_ACCESS_TOKEN@github.com/username/username.github.io.git is the destination repo
    • $PERSONAL_ACCESS_TOKEN is the authentication token which was setup earlier

Setting up the GitHub Actions workflow

Add this yaml file to the Gatsby project’s .github/workflows directory. This tutorial will name the yaml file deploy.yaml, resulting in .github/workflows/deploy.yaml.

name: Deploy site

on:
  push:
    branches: [ main ]

jobs:
  deploy-site:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout git branch
      uses: actions/checkout@v3.0.0
    - name: Setup Node.js
      uses: actions/setup-node@v3.0.0
      with:
        node-version: '16'
    - run: npm install
    - name: Deploy site
      run: |
        npm run deploy -- -m "deploy site via GitHub Actions" -u "github-actions-bot <support+actions@github.com>"
      env:
        PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

• push command will trigger ths workflow on any git push to the main branch
• uses: actions/checkout@v3.0.0 checks out the main branch
• uses: actions/setup-node@v3.0.0 installs Node.js to the environment
• - run: npm install installs npm packages dependencies
• npm run deploy -- -m "deploy site via GitHub Actions" -u "github-actions-bot <support+actions@github.com>" will run the deploy script with extra arguments for gh-pages commit to the GitHub Pages repo
  • -m "deploy site via GitHub Actions" is the commit message
  • -u "github-actions-bot <support+actions@github.com>" is the commit user
• PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }} is how the GitHub Actions secret gets pass through to the package.json

Conclusion

That’s it! Any push to the Gatsby project GitHub repo will trigger an automatic build and deploy. Assuming username.github.io was the repo name and GitHub Pages was configured, there should be a live site at https://username.github.io!

Additional Resources

• https://www.gatsbyjs.com/docs/how-to/previews-deploys-hosting/how-gatsby-works-with-github-pages/
• https://github.com/tschaub/gh-pages
• https://www.xkoji.dev/blog/set-up-a-blog-with-gatsby-github-pages-and-github-actions/