Publishing your Gatsby site to GitHub Pages is pretty straight forward actually. It’s more involved to set up a custom domain and https but I’ll likely cover that later / separately.

First up install gh-pages package

npm install gh-pages --save-dev

Add a deploy script to package.json e.g.

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

To break that down and explain…

1. Build it first
2. Use gh-pages package
3. -d = Destination folder “public” (what you want to deploy i.e. the built artifacts)
4. -b = Branch “master” (depends what you set your source in github settings of the repo)
5. -r = Repo - In my case I wanted to use the github username.github.io repo for the public pages but keep my actual source files in another private repo. If you don’t do this then gh-pages assumes you’re in a git repo and uses the configured “origin”.

You could also add "gh-pages-help": "gh-pages --help" to your scripts to easily output the help file.

So now when you run npm run deploy it should publish your site to GitHub pages. It should pop up a window to login the first time to GitHub if you’re using a credentials helper.

Note: If you’re using a custom domain like I am, you’ll need a CNAME file at the root of the published repo with your root host on the first line. Also you need to configure your DNS provider or use something like CloudFlare to do it.

You can publish to a subdomain and there is additional info on the Gatsby docs site.