GitHub Action to build and deploy your Gatsby site to GitHub Pages ❤️🎩
This GitHub Action will run gatsby build
at the root of your repository and
deploy it to GitHub Pages for you! Here's a basic workflow example:
name: Gatsby Publish
on:
push:
branches:
- dev
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- uses: enriikke/gatsby-gh-pages-action@v2
with:
access-token: ${{ secrets.ACCESS_TOKEN }}
NOTE: In order to support
npm
andyarn
, this Action relies on having abuild
script defined in yourpackage.json
file. Gatsby automatically defines this script whenever you start a new project viagatsby new
, which in turn callsgatsby build
.
This Action is fairly simple but it does provide you with a couple of configuration options:
-
access-token: A GitHub Personal Access Token with the
repo
scope. This is required to push the site to your repo after Gatsby finish building it. You should store this as a secret in your repository. Provided as an input. -
deploy-branch: The branch expected by GitHub to have the static files needed for your site. For org and user pages it should always be
master
. This is where the output ofgatsby build
will be pushed to. Provided as an input. Defaults tomaster
. -
deploy-repo: The repository expected by GitHub to have the static files needed for your site. Provided as an input. Defaults to the same repository that runs this action.
-
gatsby-args: Additional arguments that get passed to
gatsby build
. See the Gatsby documentation for a list of allowed options. Provided as an input. Defaults to nothing. -
skip-publish: Builds your Gatsby site but skips publishing by setting it to
true
, effectively performing a test of the build process using the live configuration. Provided as an input Defaults to false
Create a repository with the format <YOUR/ORG USERNAME>.github.io
, push your
Gatsby source code to a branch other than master
and add this GitHub Action to
your workflow! 🚀😃
Repo pages give you the option to push your static site to either master
or
gh-pages
branches. They also work a little different because the URL includes
a trailing path with the repository name, like
https://username.github.io/reponame/
. You need to tell Gatsby what the path
prefix is via gatsby-config.js
:
module.exports = {
pathPrefix: "/reponame",
}
Additionally, you need to tell the gatsby build
command to use it by passing
the --prefix-paths
as an argument. Here's an example workflow for that:
name: Gatsby Publish
on:
push:
branches:
- dev
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- uses: enriikke/gatsby-gh-pages-action@v2
with:
access-token: ${{ secrets.ACCESS_TOKEN }}
deploy-branch: gh-pages
gatsby-args: --prefix-paths
Provides build validation on pull request
if required:
name: Gatsby Publish
on:
pull-request:
branches:
- dev
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- uses: enriikke/gatsby-gh-pages-action@v2
with:
access-token: ${{ secrets.ACCESS_TOKEN }}
deploy-branch: gh-pages
gatsby-args: --prefix-paths
skip-publish: true
You have a custom domain you would like to use? Fancy! 😎 This Action's got you
covered! Assuming you have already set up your DNS provider as defined in the
GitHub Pages docs, all we need next is a CNAME
file at the root of your project with the domain you would like to use. For
example:
imenrique.com
Notice that it's all capitals CNAME 😊.
This is how GitHub keeps track of the domain you want to use. This action will
copy the file to the public
directory generated by Gatsby before pushing your
site so that the domain is persisted between deploys.
This Action assumes that your Gatsby code sits at the root of your repository
and gatsby build
outputs to the public
directory. As of this writing, Gatsby
doesn't provide a way to customize the build directory so this should be a safe
assumption.
Additionally, a build
script on package.json
is expected for this Action to
to work (as mentioned at the beginning). Ultimately, this is what calls gatsby build
.
Have fun building! ✨