Skip to main content

How Gatsby Works with GitHub Pages

The easiest way to push a Gatsby app to GitHub Pages is by using a package called gh-pages.

npm install gh-pages --save-dev

GitHub repository page

Add a deploy script to package.json

"scripts": {
"deploy": "gatsby build --prefix-paths && gh-pages -d public"

The --prefix-paths flag is used because your website is inside a folder like You’ll need to add your /reponame path prefix as an option to gatsby-config.js:

module.exports = {
pathPrefix: "/reponame",

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.

GitHub Organization or User page

Create a repository named like

Note: In this case you don’t need to specify pathPrefix and your website needs to be pushed to master branch.

"scripts": {
"deploy": "gatsby build && gh-pages -d public -b master",

After running npm run deploy you should see your website at

Custom domains

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 static directory.

Edit this page on GitHub