GitHub Pages

Though GitHub Pages isn’t a typical hosting platform, its ease of use means it’s a popular solution for Gatsby developers who want to host their websites directly through their GitHub repositories. There are three different options for Gatsby developers who have selected GitHub Pages for deployment:

• Use a path that corresponds to the GitHub account name and repository name, such as github-user.github.io/repository-name or github-user.github.io/docs.
• Use a github.io subdomain that corresponds to the GitHub account or organization name, such as github-user.github.io/.
• Use the subdomain solution, but configured to leverage a custom domain.

WARNING

If your Gatsby repository on GitHub is private or internal to your GitHub account or organization, any published Gatsby site will expose any information in the Gatsby build to the general public, so ensure that your repository is devoid of any sensitive data before publishing your site to GitHub Pages.

GitHub Pages can be configured through GitHub itself and the gh-pages NPM package. First, navigate to your Gatsby site’s repository on GitHub and select Settings under your repository name. Navigate to the GitHub Pages page, where you can choose a branch such as master or main if you plan to publish your Gatsby site to a github.io subdomain. You can also select gh-pages, which you’ll need to create if it isn’t represented among your branches, to publish to a path such as github-user.github.io/custom-path.

Within your Gatsby project root, install the gh-pages NPM package into your development dependencies:

$ npm install --save-dev gh-pages

To deploy your Gatsby site to a path such as github-user.github.io/repository-name, you’ll need to modify your gatsby-config.js file to account for the path prefix and your package.json file to include the path prefix in Gatsby builds. In this scenario, be sure your GitHub Pages branch is set to gh-pages. In gatsby-config.js:

// gatsby-config.js
module.exports = {
  pathPrefix: "/{repository-name}",
}

In package.json:

// package.json
{
  "scripts": {
    "deploy": "gatsby build --prefix-paths && gh-pages -d public"
  }
}

Then, to deploy, you can execute the following command, which will execute the Gatsby build and publish the public directory to GitHub Pages:

$ npm run deploy

To deploy your Gatsby site to the github-user.github.io/ subdomain without a path prefix, the site needs to be up to date with your desired production state on the main or master branch, or whichever branch is your repository’s default branch. In this scenario, there is no need to configure a path prefix or include it with the Gatsby build command. The deploy script in your package.json should instead be defined as follows:

// package.json
{
  "scripts": {
    "deploy": "gatsby build && gh-pages -d public -b master"
  }
}

Once you run the following command, your Gatsby site will be published to the subdomain rather than an internal path:

$ npm run deploy

NOTE

For more information about hosting Gatsby on GitHub Pages, consult the Gatsby documentation’s guide to using Gatsby with GitHub Pages, which contains information on using a custom domain, and deploying from a continuous integration (CI) service. Also consult the GitHub Pages documentation for more usage information.