# How to Deploy a Gatsby Site from Git on xCloud

> Deploy a Gatsby site from GitHub on xCloud. xCloud runs gatsby build, serves the public folder as a static site, and redeploys on every push.

You can host a **Gatsby** site on **[xCloud](/)** straight from its Git repository. xCloud reads your `package.json`, runs `npm run build` (which runs `gatsby build`) on your server, and serves the finished site from the `public` folder with your web server. No Node.js process keeps running. After the first deploy, every push to your branch can publish a new version.

This guide walks through the setup screen, the build settings to check, and how to add your own domain and turn on deploys on push.

## How xCloud sets up a Gatsby site

xCloud fills in these settings when your `package.json` lists `gatsby` as a dependency:

| Setting | Value for Gatsby | Why |
|---|---|---|
| **App Type** | **Node.js** | Gatsby builds with Node.js, even though the live site is static. |
| **Serving mode** | **Static build** | Your web server serves the built files. No Node.js process runs. |
| **Web root** | `public` | `gatsby build` writes your site to `public/`. |
| **Build & deploy script** | `npm install`, then `npm run build` | Runs on every deploy. |

xCloud has no separate Gatsby label yet, so the setup screen shows **Framework not recognised — assuming a static build. Review the serving mode.** For a Gatsby site, the static build it picks is the right one. You only need to check the settings in Step 4.

If your `package.json` has no `build` script, xCloud warns you to set the build command. Gatsby starters include `"build": "gatsby build"`, so most projects already have it.

## Before you begin

- An xCloud server with the **Nginx** or **OpenLiteSpeed** stack. You can also create one during these steps.
- Your Gatsby project in a Git repository. Public repositories work without any setup. For a private repository, [connect your Git provider](/docs/how-to-integrate-a-git-provider-with-xcloud/) first.
- A `build` script in `package.json`.

## Step 1: Choose Deploy via Git

Open **Sites** and click **Add New Site**. On **What would you like to host today?**, click the **Deploy via Git** card.

![Click the "Deploy via Git" card on the "What would you like to host today?" screen in xCloud](/_landing/docs/deploy-gatsby-site-on-xcloud-image-1.png)

You can also open a server first and use its **Deploy via Git** tab. Both paths lead to the same setup screen.

## Step 2: Pick the server

Under **Where should it run?**, select the server for your Gatsby site and click **Continue**. If you have no Nginx or OpenLiteSpeed server yet, choose **Deploy on a new server** and xCloud brings you back here once the server is ready.

![Select a server under "Where should it run?" for the Gatsby site and click Continue](/_landing/docs/deploy-gatsby-site-on-xcloud-image-2.png)

## Step 3: Add your Gatsby repository

In **Deploy Any App From Git**, paste your repository URL, for example `https://github.com/your-account/your-gatsby-site`, then press Enter. For a private repository, switch to **Private Repository** and pick it from your connected account.

xCloud reads the repository and selects **Native app** with a **Node.js** label, and **App Type** is set to **Node.js**.

![xCloud detects the Gatsby repository as a Native app with the Node.js app type](/_landing/docs/deploy-gatsby-site-on-xcloud-image-3.png)

Keep **Native app** selected. A Gatsby site doesn't need a Docker container.

## Step 4: Check the domain, branch and build settings

Keep the free **Staging domain (no DNS)** to test first, or click **Use a live domain instead** to use your own domain. Check that **Branch** is the branch you want to publish.

Then look at **Build & serving**. **Serving mode** should be **Static build** and **Web root** should be `public`. Leave both as they are, unless you changed where Gatsby writes its output.

![Build & serving shows Static build as the serving mode and public as the web root for a Gatsby site](/_landing/docs/deploy-gatsby-site-on-xcloud-image-4.png)

Don't switch to **SSR (Node process)**. In Gatsby starters the `start` script runs `gatsby develop`, a development server, so a static build is the right setup for a live site.

## Step 5: Check the build script and environment variables

Open **Advance**. Under **Build & deploy script**, xCloud fills in the commands that run on every deploy: install your dependencies, then `npm run build`. Change them only if your project builds with a different script.

![The Build & deploy script under Advance installs dependencies and runs npm run build on every deploy](/_landing/docs/deploy-gatsby-site-on-xcloud-image-5.png)

In the same section you can pick the **Node.js Version** your site builds with and add values to **Environment file (.env)**. Gatsby reads these values while it builds, for example a CMS API key or a `GATSBY_` variable. After you change one, deploy again so the site picks it up. [Environment Variables and Git Deployments](/docs/environment-variables-and-git-deployments-in-xcloud/) explains how xCloud stores them.

## Step 6: Deploy

Check the **Summary** and click **Deploy**. xCloud pulls your code, installs dependencies, runs `gatsby build` and publishes the `public` folder. When it is done, open **Deployments** on the site. The latest deployment shows **Deployed** and **LIVE**.

![The Deployments page shows the first Gatsby deployment as Deployed and LIVE](/_landing/docs/deploy-gatsby-site-on-xcloud-image-6.png)

Click **Visit Site** at the top to open your Gatsby site.

If a deployment fails, open it on the same page and read **Build steps** to see which step stopped. Common causes for Gatsby:

- **The build failed.** Open **Raw output** and look for the Gatsby error. A plugin that needs a newer Node.js version is a frequent one: change the version as shown in [How to Change Node Version with xCloud](/docs/how-to-change-node-version-with-xcloud/), then click **Deploy Now**.
- **The site shows an error after a successful build.** Check that **Web root** is `public`. Gatsby writes nothing to `dist`.

See [How to View Git Deployments for Your Site in xCloud](/docs/view-git-deployments-in-xcloud/) for more on this page.

## Update your site with a Git push

After the first deploy, publishing a change is a push:

1. Turn on **Auto-deploy on push (webhook)** for a repository from a connected Git provider.
2. Push to the branch you deployed. xCloud pulls the new code and rebuilds the site.
3. To deploy without a push, click **Deploy Now** at the top of the site.

If a push doesn't start a deployment, see [Troubleshooting Git Deployments](/docs/troubleshooting-git-deployments-stuck-failed-or-not-triggering/).

## Add your own domain and SSL

If you started on a staging domain, add your own domain from the site's **Domain** menu, point its DNS to your server, and xCloud sets up a free SSL certificate. [How to Deploy Git Projects in One Click with xCloud](/docs/deploy-git-projects-in-one-click-with-xcloud/) shows the DNS options, including one-click verification for domains on Cloudflare.

Building with Astro instead? See [How to Deploy an Astro Site from Git on xCloud](/docs/deploy-astro-site-on-xcloud/).

## Frequently asked questions

### Does xCloud run a Node.js process for my Gatsby site?

No. xCloud builds your Gatsby site with `npm run build` and your web server serves the files in the `public` folder. No Node.js process stays running after the build.

### Why does xCloud say "Framework not recognised" for my Gatsby repository?

xCloud has no separate Gatsby label yet, so it shows the app as Node.js and assumes a static build. For Gatsby that is the right setup. Check that **Serving mode** is **Static build** and **Web root** is `public`, then deploy.

### Can I use Gatsby SSR, deferred static generation or Gatsby Functions on xCloud?

Not with a static build. Those features need a running Gatsby server, and a static build only serves the files gatsby build writes. Pages generated at build time work as usual.

### How do I update my Gatsby site after it is live?

Push to the branch you deployed. With Auto-deploy on push turned on, xCloud rebuilds the site and publishes the new version. You can also click Deploy Now on the site.

That's it! Your Gatsby site is live on xCloud and updates whenever you push.

Still stuck? Contact our **[dedicated support team](/docs/access-built-in-support-portal-in-xcloud/)** for any of your queries.
