Get Started with Gatsby Cloud

On this page, you'll learn how to set up and deploy your project on Gatsby Cloud with your Prismic repository.

Gatsby Cloud is a platform to build, serve, and preview Gatsby projects. Let's compare its features with other services to understand how Gatsby Cloud fits into a project's stack:

• Hosting: Serves your site to your visitors. Gatsby Cloud Hosting is like Netlify, Vercel, or Amazon S3.
• Build: A continuous integration service to build your site on content changes. Gatsby Cloud Builds are like Netlify Builds.
• Preview: A staging site to preview your draft documents before you publish. Gatsby Cloud Previews are like Prismic Previews. When changes are published in Prismic, Gatsby Cloud will rebuild your site.
• Functions: Serves your site's API routes if included in the project. Gatsby Cloud Functions is like Netlify Functions.

After completing this guide, you will be able to preview content changes and rebuild your project.

Preview content changes by following these steps:

1. Save and publish content changes to a specific Release in Prismic.
2. Gatsby Cloud updates a preview version of your site.
3. Click the Preview button in Prismic to open the preview site.

When the changes are ready to be published, you can deploy your changes by following these steps:

1. Save and publish content changes for a document in Prismic.
2. Gatsby Cloud rebuilds the site.
3. The site is deployed with the new content.

Complete the following steps in your Prismic repository.

1. Open your Prismic Dashboard and select your repository.
2. At the top of the page, click the Planned tab.
3. Create a new Release named Gatsby Cloud Preview
4. Add or edit documents and save them to the newly created Release (learn how to save to a Release).

You will need the Release's ID to set up Gatsby Cloud later in the guide.

You can find the Release ID in the API Browser of your repository. Go to the following URL, but replace your-repository-name with the name of your repository:

Click the unlock icon and select the corresponding ref for the Gatsby Cloud Preview Release from the dropdown menu. Then you'll see the release ID at the right.

Next, generate an access token. In this case, you'll need two tokens: one for builds and one for previews.

• Builds: After generating the first token, you should see the Access to master token. You'll use this token for the Gatsby Cloud Builds server:

• Previews: Now, create a new token below. Select Access to Master + Releases and then click Add a token. You'll use this token for the Gatsby Cloud Preview server.

Set these tokens in one of two places:

• Open the settings of your Gatsby Cloud Dashboard. Then add the tokens in the Environment variables.
• Or, if you prefer, you can create an .env file in your project's root and add them there. The source plugin settings from the gatsby-config.js file will consume these variables. If you set it up like this, Gatsby Cloud will automatically read these values when you set up your site.

We'll guide you through configuring these variables in Gatsby Cloud further below in this article. You can learn more about managing environment variables in Gatsby's documentation.

Complete the following steps in your Gatsby project's code.

Install and configure the required plugins to build and preview your site. Follow the main installation guides for each one:

• gatsby-plugin-gatsby-cloud: Generates files specific to Gatsby Cloud. For example, redirects are converted with createRedirect with gatsby-node.js so that Gatsby Cloud can manage them.
• gatsby-source-prismic: The source plugin to retrieve data from your Prismic repository.

• gatsby-plugin-prismic-previews: This plugin allows you to Integrate live Prismic Previews into your Gatsby project.

Sign up or log in to GitHub and push your project to a new repository. We'll use this repository for the Gatsby Cloud integration.

The following steps will take place on Gatsby Cloud.

Sign in to Gatsby Cloud using the Login with GitHub option. It'll ask you to authorize the Gatsby Cloud app with your GitHub account. If you need access to one or more repositories, you can click Request access now or later when creating an instance.

Once signed in, follow the following steps:

1. Import from a GitHub repository: Once logged in, click +Add a site and select Import from a GitHub repository.
2. Select Git as the provider.
3. Pick your Gatsby site from your list of GitHub repositories. Then select the branch where you pushed your project, usually named main. Click Next.
4. Click Skip this step to configure Prismic manually.
5. Click Create site. It will create your instance in Gatsby Cloud.

Environment variables are used in Gatsby Cloud to authorize your site when pulling content from Prismic.

Gatsby Cloud will automatically detect your environment variables in your gatsby-config.js. However, consider adding any additional variables that automatic detection may have missed.

To edit your site's environment variables on Gatsby Cloud, navigate to the following page:

1. Open your site's Dashboard
2. Select the Site Settings tab under your site's name
3. In the sidebar under General, navigate to Environment variables

Once there, add the following variables.

Under the Build variables tab:

• PRISMIC_REPO_NAME: Your repository name.
• PRISMIC_API_KEY: The token you set up in your Prismic repository for builds.

Under the Preview variables tab:

• PRISMIC_REPO_NAME: Your repository name.
• PRISMIC_API_KEY: The token you set up in your Prismic repository for previews.
• PRISMIC_RELEASE_ID: The Release ID you previously saved.

Use Webhooks to notify Gatsby Cloud when the content in Prismic changes.

In your Gatsby Cloud site dashboard, navigate to the Site Settings tab.

Scroll down to Preview Webhook and copy the URL listed in the box.

Next, add the webhook to your Prismic repository.

1. In your Prismic repository, navigate to Settings > Webhooks.
2. Click the Create a webhook button.
3. Name the webhook "Gatsby Cloud Preview."
4. Paste the Preview webhook URL copied from Gatsby Cloud into the URL field.
5. Ensure all checkboxes under Triggers > Releases are checked.
6. Click the Add this webhook button.

Back in your Gatsby Cloud site dashboard, navigate the Site Settings tab.

Scroll down to Builds Webhook and copy the URL listed in the box.

Next, add the webhook to your Prismic repository. The process is the same as the webhook for previews but with a different URL.

1. In your Prismic repository, navigate to Settings > Webhooks.
2. Click the Create a webhook button.
3. Name the webhook "Gatsby Cloud Builds."
4. Paste the Builds webhook URL copied from Gatsby Cloud into the URL field.
5. Ensure all checkboxes under Triggers > Releases are unchecked.
6. Click the Add this webhook button.

Now the production build will automatically update when you publish changes in Prismic.

Navigate to your Gatsby Cloud dashboard. Adjacent to the Site Settings tab, select the CMS Preview tab on the far right.

Copy the URL that appears in the middle of the page (it should start with "preview-").

Next, set up your Prismic repository for the Preview URL.

1. In your Prismic repository, navigate to Settings and select Previews in the sidebar.
2. Click the Create a Preview button.

Fill out the form with the following values:

• Site Name: "Gatsby Cloud Preview"
• Domain for your application: Paste the CMS Preview URL copied from Gatsby Cloud.
• Preview Route: /preview/.

That's it. Now your Gatsby Cloud integration is ready to rebuild your site when you publish content in Prismic. And your Prismic repository has a dedicated Prismic Release to preview content before publishing, plus you can share a preview URL with your team.