How Gatsby Works with GitHub Pages
GitHub Pages is a service offered by GitHub that allows hosting for websites configured straight from the repository. A Gatsby site can be hosted on GitHub Pages with a few configurations to the codebase and the repository’s settings.
You can publish your site on GitHub Pages several different ways:
- to a path like
- to a subdomain based on your username or organization name:
- to the root subdomain at
username.github.io, and then configured to use a custom domain
You must select which branch will be deployed from your repository settings in GitHub for GitHub Pages to function. On GitHub:
Navigate to your site’s repository.
Under the repository name, click Settings.
In the GitHub Pages section, use the Source drop-down to select
main(for publishing to the root subdomain) or
gh-pages(for publishing to a path like
/docs) as your GitHub Pages publishing source.
The easiest way to push a Gatsby app to GitHub Pages is by using a package called gh-pages.
A custom script in your
package.json makes it easier to build your site and move the contents of the built files to the proper branch for GitHub Pages, this helps automate that process.
For sites deployed at a path like
--prefix-paths flag is used because your website will end up inside a folder like
username.github.io/reponame/. You’ll need to add your
/reponame path prefix as an option to
Then add a
deploy script to
package.json in your repository’s codebase:
When you run
npm run deploy all contents of the
public folder will be moved to your repository’s
gh-pages branch. Make sure that your repository’s settings has the
gh-pages branch set as the source to deploy from.
Note: To select
gh-pages as your publishing source, you must have the branch present in your repository. If you don’t have a
gh-pages branch, you can create them and then return to source settings to change your publishing source.
⚠️ As your repository will grow and get more commits, so will your
gh-pagesbranch. This might slow down operations like clone and increase disk usage. To address this, use the
-foption from the
gh-pagescommand to avoid keeping an history of the GitHub Pages branch.
For a repository named like
username.github.io, you don’t need to specify
pathPrefix and your website needs to be pushed to the
⚠️ Keep in mind that GitHub Pages forces deployment of user/organization pages to the
mainbranch. So if you use
mainfor development you need to do one of these:
- Change the default branch from
mainto something else, and use
mainas a site deployment directory only:
- To create a new branch called
sourcerun this command:
git checkout -b source main
- Change the default branch in your repository settings (“Branches” menu item) from
- Note: GitHub Pages lets you use any branch for deployment, see this docs page on how to do this. This means you do not necessarily have to change your default branch.
- Have a separate repository for your source code (so
username.github.iois used only for deployment and not really for tracking your source code). If you go down this route, you will need to add an extra option for
--repo <repo>(works for https and git urls) in the gh-pages command below.
If you are deploying to branch different to
main, replace it with your deployment branch’s name in the deploy script.
npm run deploy you should see your website at
If you use a custom domain, don’t add a
pathPrefix as it will break navigation on your site. Path prefixing is only necessary when the site is not at the root of the domain like with repository sites.
Note: Don’t forget to add your CNAME file to the
It’s also possible to deploy your website to
gh-pages through a CI server. This example uses Travis CI, a hosted Continuous Integration service, but other CI systems could work as well.
You can use the gh-pages npm module to deploy. But first, you need to configure it with proper credentials so that
gh-pages is able to push a new branch.
To push changes from the CI system to GitHub, you’ll need to authenticate. It’s recommended to use GitHub developer tokens.
In GitHub go to your Account settings -> Developer settings -> Personal access tokens, and create a new token that provides the
repo access permissions.
In Travis’s settings for the repository, add a new secret environment variable of the name
GH_TOKEN with the value of the token copied from GitHub. Make sure you DO NOT toggle the “display in build logs” setting to on as the token should remain secret. Otherwise, strangers would be able to push to your repository (a big security issue).
Update the Gatsby project’s
package.json to also include a
deploy run script which invokes
gh-pages with two important command-line arguments:
-d public- specifies the directory in which the built files exist and will be pushed as a source to GitHub Pages
-r URL- the GitHub repository URL, including the use of the secret GitHub token (as a secret environment variable) to be able to push changes to the
gh-pagesbranch, in the form of
https://$GH_TOKEN@github.com/<github username>/<github repository name>.git
Here’s an example (be sure to update the user and repo names to your own):
.travis.yml configuration provides a reference:
To break down the important bits here for deploying the Gatsby website from Travis to GitHub Pages:
before_scriptis used to install the Gatsby CLI so it can be used in the project’s run script to build the Gatsby website
deploywill only fire when the build runs on the
mainbranch, in which case it will fire off the deploy script. In the above example, the Gatsby site is located in a
docs/directory. The script changes into that directory, installs all the website dependencies, and runs the deploy script as was set in the previous step.
Committing and pushing both the
package.json files to your base branch will be the final step in the process.