How to deploy Gatsby to GitHub Pages

In short

The settings

Pages source

GitHub Actions

Build

npx gatsby build --prefix-paths

Folder it publishes

public

Live at

USERNAME.github.io/REPO

Step by step

Set it up

1. 1

   Set the base path

   A GitHub Pages project site lives in a subfolder, USERNAME.github.io/REPO, so the build has to know that folder's name.

   Add a pathPrefix with the repository name. The workflow builds with --prefix-paths so Gatsby uses it.

   module.exports = {
     pathPrefix: '/REPO',
     // ...your siteMetadata and plugins
   };

2. 2

   Add the workflow

   Create .github/workflows/deploy.yml in the repository with the file below. It builds the site on every push to main and publishes the result.

   name: Deploy to GitHub Pages
   
   on:
     push:
       branches: [main]
     workflow_dispatch:
   
   permissions:
     contents: read
     pages: write
     id-token: write
   
   concurrency:
     group: pages
     cancel-in-progress: false
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - uses: actions/setup-node@v7
           with:
             node-version: lts/*
             cache: npm
         - id: pages
           uses: actions/configure-pages@v6
         - run: npm ci
         - name: Build
           run: npx gatsby build --prefix-paths
         - uses: actions/upload-pages-artifact@v5
           with:
             path: public
   
     deploy:
       needs: build
       runs-on: ubuntu-latest
       environment:
         name: github-pages
         url: ${{ steps.deployment.outputs.page_url }}
       steps:
         - id: deployment
           uses: actions/deploy-pages@v5
   

3. 3

   Switch Pages to GitHub Actions

   In the repository on GitHub, open the Pages settings and set the source to GitHub Actions. This is a one-time switch.

   Settings→Pages→Build and deployment→Source: GitHub Actions

4. 4

   Push, then open your site

   Commit and push to main. The Actions tab shows the build; when it turns green, the site is at https://USERNAME.github.io/REPO/. Every push after that deploys again.

Good to know

Common snags

• The workflow uses npm. With pnpm or Yarn, change the install line and the cache setting to match.

Questions

Before you start

Next step: connect your own domain to GitHub Pages.