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

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

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