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
- A Gatsby project set up. (Need help creating one? Follow the Quick Start)
- A GitHub account
Configuring the GitHub Pages source branch
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.
- Click “Save”.
The best way to push a Gatsby app to GitHub Pages is by using a package called gh-pages.
Using a deploy script
You can add a custom
deploy script to the
"scripts" section of your
package.json. This will make it easier to publish your Gatsby site to GitHub pages. See the instructions below how to configure it (as it depends on what option you’ll choose).
Deploying to a path with pathPrefix
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.
Deploying to a GitHub Pages subdomain at github.io
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
Deploying to the root subdomain and using a custom domain
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
You can use GitHub actions to push your Gatsby site to GitHub Pages. See the Gatsby Publish Action for more information.
GitHub Pages doesn’t support advanced features like SSR, DSG, or Image CDN. You can get all features and faster builds by signing up to Gatsby Cloud.