How to deploy a Gatsby site
Gatsby compiles your React app into plain static files, so deploying it is mostly about building cleanly and pushing one folder to a host. Here's the whole flow — build, host, and automate — with the 2026 pitfalls called out.
To deploy a Gatsby site:
- Build → run
gatsby build; it outputs the whole site to thepublic/folder. - Host → upload
public/to any static host — Netlify, Vercel, Cloudflare Pages, GitHub Pages, S3+CloudFront, or any web server. - Automate → run the build in a CI/CD pipeline so every
git pushrebuilds and redeploys. - Watch out for → Node 18+, the
GATSBY_env-var prefix, and--prefix-pathsfor subdirectory hosting.
Before you start
What a Gatsby deploy actually is
Gatsby is a React-based static site generator. When you run gatsby build, it pulls data through GraphQL, renders every page to HTML, optimises images, and writes the finished site — HTML, CSS, JavaScript and assets — into a single public/ directory. Deploying is then just serving that folder.
Because the output is static, you can host it almost anywhere. The one exception is Gatsby's SSR and Deferred Static Generation (DSG) rendering modes: pages built that way run on demand and need a Node.js runtime, so a pure static bucket won't serve them. If your site is standard SSG (the common case), plain static hosting is all you need.
A 2026 reality check: Gatsby still works, but it's effectively in maintenance mode. Netlify acquired Gatsby Inc. in February 2023, the last major release (Gatsby 5) shipped in November 2022, and much of the once-huge plugin ecosystem is now unmaintained. Existing sites deploy fine — this guide keeps yours shipping — but for a brand-new project it's worth weighing Astro or Next.js too.
Prerequisites
What you need first
Three things, and you're ready to ship.
Node.js 18+
Gatsby 5 requires Node.js 18.0.0 or newer. Check with node -v. Pin the same version locally and in CI to avoid dependency surprises.
The Gatsby CLI
Installed with your project (npm i) or globally via npm i -g gatsby-cli. It provides gatsby build and gatsby serve.
A Git repo & a host
Your source in Git (for CI/CD), and a static host or CDN to serve public/. Pick the host in step 4.
Step by step
Deploy a Gatsby site in 5 steps
From a clean checkout to a live URL. Steps 1–4 are the manual flow; step 5 automates all of it.
Install dependencies
From your project root, install everything the build needs. Committing a lockfile keeps CI reproducible.
node -v # expect v18.x or newer npm ci # clean, lockfile-exact install
Build the production bundle
One command compiles the whole site into public/. This is the artifact you deploy — nothing else from the repo is served.
npx gatsby build # writes the finished site to ./public
Test the build locally
Never ship the dev server. gatsby serve serves the real public/ output on localhost:9000 so you catch broken paths or missing assets before they go live.
npx gatsby serve # preview the production build at http://localhost:9000
Upload public/ to a host
Serve the contents of public/ from any static host or CDN. A couple of common paths:
# AWS S3 + CloudFront aws s3 sync ./public s3://your-bucket --delete aws cloudfront create-invalidation --distribution-id ABC123 --paths "/*" # or any server over rsync/SFTP rsync -avz --delete ./public/ user@host:/var/www/site/
Deploying under a subpath (e.g. example.com/blog)? Set pathPrefix in gatsby-config.js and build with --prefix-paths, or Gatsby ignores it and asset links break. See Adding a Path Prefix.
Automate it with CI/CD
Doing steps 1–4 by hand on every change gets old fast — and one skipped gatsby build ships a stale site. Wire it into a pipeline so every push to main installs, builds, and deploys automatically. That's what the next section covers.
Don't get caught out
Common Gatsby deploy pitfalls
The failures that eat an afternoon — and how to avoid each one.
The GATSBY_ env-var prefix
Only variables prefixed GATSBY_ reach the browser bundle; they're baked in at build time. Change one → rebuild. And never put a secret in a GATSBY_ var — it ships to every visitor.
Missing --prefix-paths
Hosting under a subdirectory without the flag makes Gatsby build for the root, so CSS/JS 404s. Add --prefix-paths (or PREFIX_PATHS=true) to the build.
Cold, slow builds
Cache .cache/ and public/ between CI runs to keep incremental builds fast. Drop the cache when you bump Gatsby or plugin versions to avoid stale-cache bugs.
SSR/DSG on a static host
SSR and DSG pages need a Node runtime. On a pure static bucket they won't render — either keep pages fully static (SSG) or deploy to a host that runs Node.
Aging plugins
With the ecosystem in maintenance mode, a Node upgrade can surface plugin breakage. Pin versions, keep a lockfile, and test the build in CI before it hits production.
Out-of-memory builds
Large image-heavy sites can exhaust memory during gatsby build. Give the CI runner enough RAM, or raise Node's heap with NODE_OPTIONS=--max-old-space-size.
Automate the whole flow
Build once, deploy anywhere — with a pipeline
Gatsby's job ends at public/. The reliable way to get that folder live on every change is a CI/CD pipeline that owns the build and the deploy. Buddy fits this cleanly: it has a dedicated Gatsby CLI action, and it deploys the result to whatever host you already use.
Dedicated Gatsby CLI action
The Gatsby CLI action runs gatsby build in a container with Node and gatsby-cli preinstalled — no runner setup.
Own the build, choose the host
Deploy public/ to Netlify, S3 + CloudFront, SFTP, or anywhere else — the build stays yours.
Env vars & secrets in one place
Manage build-time GATSBY_ variables and encrypted secrets in the pipeline, so every build is reproducible and nothing sensitive lands in the repo.
Cache & parallelise
Persist .cache/ between runs for fast incremental builds; parallelise tests and deploys in the same pipeline.
Push-to-deploy
Trigger on push to main: install → build → deploy, every time, with a rollback if a deploy goes wrong.
Know when it ships
Wire Slack or email notifications so the team sees each deploy — green or red.
Stand up a live preview
Buddy can also run a version of the site, not just build it: a static preview per branch, or — because Gatsby's dev server and SSR/DSG need Node — a live gatsby develop instance on a sandbox.
A minimal Gatsby pipeline is three actions — install, build, deploy:
- pipeline: "Build & deploy Gatsby"
trigger_mode: ON_EVERY_PUSH
ref_name: refs/heads/main
actions:
- action: "Build site"
type: "BUILD"
docker_image_name: "library/node"
docker_image_tag: "18"
execute_commands:
- "npm ci"
- "npx gatsby build"
cached_dirs:
- "/buddy/.cache" # keep Gatsby's cache warm
- action: "Deploy public/"
type: "..." # Netlify, S3, SFTP — your host
Where to host
Gatsby hosting options, compared
Any of these serves a static Gatsby build. The differences are the build story around them.
| Host | Static (SSG) | SSR/DSG | Built-in CI/CD | Free tier | Best for |
|---|---|---|---|---|---|
| Netlify | ✓ | ✓ | git-based | ✓ | Gatsby's current owner; zero-config |
| Vercel | ✓ | ✓ | git-based | ✓ | Preview deploys, edge network |
| Cloudflare Pages | ✓ | partial | git-based | ✓ | Generous free bandwidth |
| GitHub Pages | ✓ | ✗ | Actions | ✓ | Simple docs/portfolio sites |
| AWS S3 + CloudFront | ✓ | ✗ | ✗ bring your own | pay-as-you-go | Full control, own infra |
Features and free tiers change often — check each provider for current terms. Compiled July 2026.
Official docs: Gatsby deploy guides · Netlify · Vercel · Cloudflare Pages
Go deeper
Deployment tutorials & further reading
Step-by-step guides for automating the flow and for each specific host — all primary sources.
CI/CD for Gatsby
Build, test and deploy a Gatsby site on every push to Git — the full pipeline, step by step.
Gatsby CLI action
Run gatsby build in a preconfigured pipeline action — Node and gatsby-cli already installed.
Continuous Deployment
What continuous deployment means for a Gatsby site, and why automating build+deploy pays off.
Deploy & hosting hub
The official index of every host-specific Gatsby deploy guide — the canonical reference.
Deploying to Netlify
Deploy a Gatsby project to Netlify — Gatsby's current owner and a zero-config path.
Deploying to S3/CloudFront
Host a Gatsby site on your own AWS infra with S3 storage behind a CloudFront CDN.
Gatsby on GitHub Pages
Deploy to GitHub Pages, including the pathPrefix setup a project subpath needs.
Adding a Path Prefix
Serve a Gatsby build from a subdirectory correctly with pathPrefix and --prefix-paths.
A fair call
Keep Gatsby, or move on?
Deploying an existing Gatsby site is straightforward. Whether to start a new one is a different question.
Gatsby still deploys fine if…
- You already run a Gatsby site — this flow keeps it shipping.
- Your build is standard SSG with a stable, pinned plugin set.
- You value Gatsby's GraphQL data layer and image pipeline.
- You lock Node and dependency versions in CI.
Weigh an alternative if…
- You're starting greenfield — Astro and Next.js are more actively developed.
- You depend on plugins that are no longer maintained.
- Every Node upgrade turns into a dependency-fix expedition.
- Whatever you pick, a CI/CD pipeline makes the build+deploy portable.
Common questions
Deploying Gatsby — common questions
Where does Gatsby put the built site?
Running gatsby build compiles your React components, processes images, and writes static HTML, CSS, JS and assets to the public/ directory at your project root. That folder is the complete, deployable site — upload its contents to any static host.
What do I need to deploy a Gatsby site?
Gatsby 5 requires Node.js 18 or newer. You need the gatsby-cli (installed as a dev dependency or globally), your project source in a Git repository, and a static host or CDN to serve the public/ folder.
Can I host a Gatsby site anywhere?
Yes. A standard SSG Gatsby build is plain static files, so it runs on Netlify, Vercel, Cloudflare Pages, GitHub Pages, AWS S3 + CloudFront, or any web server. If you use Gatsby's SSR or DSG rendering, those pages need a Node.js runtime rather than a pure static host.
Why aren't my environment variables working in the browser?
Only variables prefixed with GATSBY_ are embedded into the client-side bundle at build time and readable via process.env.GATSBY_VARIABLE. Unprefixed variables stay server/build-only. Because they are baked in at build time, changing a GATSBY_ value requires a rebuild — and never put a secret in a GATSBY_ variable.
How do I deploy Gatsby to a subdirectory?
Set pathPrefix in gatsby-config.js and build with the --prefix-paths flag (or PREFIX_PATHS=true). Without that flag Gatsby ignores pathPrefix and builds as if hosted at the domain root, which breaks asset links under a subpath.
Should I use Gatsby for a new site in 2026?
Gatsby still builds and deploys, but it is effectively in maintenance mode: Netlify acquired Gatsby Inc. in February 2023, the last major release (Gatsby 5) shipped in November 2022, and much of the plugin ecosystem is unmaintained. Existing Gatsby sites deploy fine; for greenfield projects, evaluate Astro or Next.js too.
How do I automate Gatsby deployments?
Use a CI/CD pipeline that installs dependencies, runs gatsby build, and deploys public/ on every push. Buddy has a dedicated Gatsby CLI action plus deploy actions for Netlify, S3, CloudFront and SFTP, so one pipeline covers build and deploy.