Getting started with Gatsby Cloud & Prismic

Gatsby Cloud allows you to integrate your site with Prismic to run efficient builds and preview content changes made in the CMS before publishing. Start using these powerful tools by following this step by step guide.


🕙 Before Reading

This article assumes that you have already created an account with Prismic.

This tutorial also requires you to:

  1. Have a Github account.
  2. Have a Gatsby Cloud account.

You can create them now or later when following the next steps of this guide.

Configure a Gatsby project

To carry out the integration, you will need a project. Select the option according to your case:

A) I don't have a project yet

If you don't have an existing Gatsby project, try out one of our sample projects. They have all the required Preview configuration you'll need for this integration. Select one, and once it's up and running on your machine, jump to step 2. Create a Release.

B) I have an existing project

If you already have a Gatsby + Prismic project that uses the gatsby-source-prismic plugin, continue reading to configure previews.

1. Configure previews in your project

If you are working with any of our example projects, skip this step and directly go to 2. Create a Release.

If not, read the Preview article to learn how to set-up your project code to be ready for this integration, and then come back.

2. Create a Release

Go to your Dashboard, open your repository, click on the Planned tab, and create a new Release.

Click on the green pencil button to create a new document, add text to the UID field, select one Slice from the options below, add content to it, and save.

3. Find and save the Release ID for later

You can find the release ID in the API browser of your repository. Go to the following URL. Don't forget to replace your-repository-name with the name of your repo:

Copy
https://your-repository-name.prismic.io/api/v2

Click the unlock icon and select the corresponding ref ID for your release.
(You may get a pop up asking for access, accept it, then you'll be redirected to the API browser again):

📌 Hold on to this release ID

We'll use it later when adding the environment variables in Gatsby Cloud.

4. Create API tokens

First, 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 one on the gatsby-build/production server:
  • Previews: Now, create a new token below. Select Access to Master + Releases and then click "Add a token". You'll use this one for the Gatsby Cloud Preview.

These Tokens need to be then set in one of two places:

  • In the Environment variables in the settings of your Gatsby Cloud Dashboard.
  • Or, If you prefer, you can create an .env file in your project's root and add them there. The variables will be consumed in the gatsby-config.js file. If you set it up like this, Gatsby Cloud will try and read these values when you make the Integration.

We'll guide you through configuring these variables in Gatsby Cloud further below in this article. Learn more about Managing environment variables.

5. Create a Github repository

Create a Github repository and push your project. We'll use this repository for the Gatsby Cloud integration.

Connect Gatsby Cloud

1. Sign in to Gatsby Cloud

Select Sign in with GitHub. You’ll be asked to authorize the Gatsby Cloud app with your GitHub account. If you need to request access to one or more repositories, you can click “request access” now or later when creating an instance.

2. Add a site

Once signed in, follow the next steps:

  • Import from a Git repository: Once you’ve logged in, click +Add a site and select 'Import from a Git repository'.
  • Select Git as the provider.
  • Repository: Pick your Gatsby site from your list of GitHub repositories. Then select the branch where you pushed your project; this is usually named Master or Main. Click 'Next'.

💡 If you don’t see your site

If you don’t see your site, it might be because it belongs to a GitHub organization rather than your personal account. You can connect to a new GitHub Organization.

💡Repositories must contain one Gatsby project

Repositories must contain one Gatsby project configured at their root to be enabled. Gatsby Cloud works best with Gatsby version 2.20.16 and higher.

  • Integrations: Click “Skip this step” to configure Prismic manually, then press “Create site” which will create your instance in Gatsby Cloud!

3. Add environment variables

You will need to add the following environment variables in Gatsby Cloud to authorize your instance & pull source data from Prismic. Gatsby Cloud will automatically try and detect these in your gatsby-config.js. However, consider adding any additional variables that automatic detection may have missed.

To do so, go to your Gatbsy Cloud Dashboard > Site Settings > Environment variables and add the following variables with the correct values.

For previews

  • PRISMIC_REPO_NAME: Your repository name
  • PRISMIC_API_KEY: The token you set up in your repo for previews.
  • PRISMIC_RELEASE_ID: The release ID you previously saved.
  • PRISMIC_PREVIEW_PATH: This requires you to have a Preview set up in your Prismic repository; we will do this in a later step. But for now, create a new one by clicking Add variable + and set it to /preview.

For builds

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

Set up webhooks

You’ll need to configure Webhooks in Prismic so that content changes can be pushed to Gatsby Cloud.

1. Webhook to preview releases

Navigate to Gatbsy Cloud Dashboard > Site Settings scroll down and Copy the Preview Webhook link on that page.

Then, In your Prismic repository, go to Settings > Webhooks and click Create a webhook. Give it a name and paste the Preview Webhook link into the URL field. Leave all the default triggers checked, and click Add this webhook.

2. Webhook for Builds

Again, navigate to Gatbsy Cloud Dashboard > Site Settings scroll down, and Copy the Builds Webhook on that page

Then again, In your Prismic repository, go to Settings > Webhooks and click Create a webhook. Give it a name and paste the Builds Webhook link into the URL field.

Uncheck the "release is created" and "release is edited or deleted" triggers, and click Add this webhook. Now the production build will automatically update when changes are published in Prismic.

Enable Previews in your repository

Navigate to your Gatsby Cloud dashboard, and on the far right, next to the Site Settings tab, you should see the CMS preview button, click on it, and copy the preview URL.

Then, go to your repository and Set up a new preview in Settings > Previews. Fill up the settings:

  • Site Name: A reference name for your Preview.
  • Domain for your application: Here, paste the CMS preview URL from Gatsby Cloud.
  • Link Resolver: The preview path, you use this in the preview variable PRISMIC_PREVIEW_PATH as /preview.

Use Gatsby Cloud's preview instance

At this point, you should have everything you need to start using the preview feature.

  • You have correctly configured your Gatsby cloud integration.
  • You have a dedicated Prismic release to preview your pages.
  • You've set up all the necessary Environment variables for Gatsby cloud.

You should now be able to preview a release when clicking the eye button on your release documents.

Unpublished documents outside of a release

For the moment, documents that have never been published and that aren't added into a release cannot be previewed when using this integration.

Wrapping Up

After integrating your Gatsby + Prismic project manually, you now have an instance of Gatsby Cloud configured with environment variables, and a provided Gatsby Preview instance you can share with your team, edit content, and watch it appear live in Gatsby Cloud!