Gatsby Cloud Docs

Getting Started with Gatsby Cloud and Contentful

See how to connect Gatsby Cloud with Contentful

Table of Contents

What are Gatsby Cloud and Contentful, and why use them together?

Contentful is a headless CMS that content editors can use to edit and publish content. Gatsby Cloud allows you to integrate your site with Contentful in order to run performant builds and preview content changes made in the CMS before publishing.

To enable you to make previews a lot faster, this doc will also show you how to setup the Contentful sidebar with Preview. This is what the Gatsby Preview button will look like once finish going through the steps in this doc.

Contentful Preview button in the sidebar

Signing 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” here or later, when creating an instance.

Once signed in, configuring Gatsby Cloud with Contentful requires several steps that are walked through below.

Creating an instance

Once you’ve authenticated with Cloud and GitHub, you can create an instance from the “Create a new Gatsby Cloud site” page.

Use the “I already have a Gatsby site” flow to setup your existing site.

Add my own site

Pick your Gatsby site from the list of GitHub repositories. You can use the search input to narrow down the list.

Gatsby Cloud Add an instance page

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 a new GitHub Organization.

Note: 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.

Select branch and publish directory

You’ll need to select a branch and then indicate the publish directory where the gatsby-config.js lives. If you leave the field blank, it defaults to the root of the site. Optionally, you may change the site name.

Select branch and directory

Once the branch and base directory are correct, select “Next.”

Create the instance

Integration Step

Quick Connect

Find Contentful in the list, press “Connect” and follow the set-up instructions to link Contentful with Gatsby Cloud.

Once you’ve authorized Contentful and selected the appropriate organization, press “Create site” which will create your instance.

Manual Setup

If you'd rather not use Quick Connect follow the steps below:

First, click “Skip this step” to configure Contentful.

Gatsby Cloud will automatically try and detect environment variables necessary in your gatsby-config.js. However — you may need to add any additional variables that automatic detection missed. See “Setting up Environment Variables” for more info.

Note that you will be able to add, delete, or update these later on in “Site Settings”.

Once you’ve added the necessary environment variables, you can press “Create site” which will create your instance in Gatsby Cloud!

Setting up Environment Variables

An environment variable references a value that can affect how running processes will behave on a computer, for example in staging and production environments. You must save environment variables in Gatsby Cloud to authorize your instance to pull source data from Contentful.

You will need to add into Gatsby Cloud any environment variable required for your app to run, such as deployment or test environment configuration settings.

You will also need to add in the following Gatsby Cloud-specific environment variables:

  • Contentful Space ID
  • Contentful Preview API access token
  • Contentful Host

These environment variables need to be in both your gatsby-config.js and your Gastby Site settings with identical names so your instance knows how to find them in your Gatsby Cloud settings.

Note that you can set environment variables for both Preview and Builds, allowing you to use different values as needed. Consider the difference as staging versus production environments. You likely want to see draft content in Preview, but not in Build.

Environment variables in your gatsby-config.js:

In your gatsby-config.js file, follow these steps:

  • In GitHub, navigate to the Gatsby site you selected for your instance

  • Navigate to the gatsby-config.js file at the root of the site - If you don’t have a gatsby-config.js file, create one

  • In the gatsby-config.js file, check that your contentfulConfig includes these 3 items - CONTENTFUL_SPACE_ID - CONTENTFUL_ACCESS_TOKEN - CONTENTFUL_HOST

If your gatsby-config.js file does not contain the three environment variables above, add them to the file and save the changes, making sure the changes have been pushed to your repository on GitHub.

If you have additional environment variables listed in your gatsby-config.js file that are necessary for your app to run, you’ll also need to include those environment variables in Gatsby Cloud.

Copy your environment variables to Gatsby Cloud

Next, you’ll need to copy environment variables from Contentful and paste them into your “Site Settings” in the Gatsby Cloud app. The order of the variables does not matter.

Finding your Space ID and Preview API Access Token in Contentful

Select API Keys from the Settings dropdown menu

Image of settings dropdown in Contentful with API keys option highlighted

From the list, select the site you want to view API Keys for. If you haven’t generated the API Keys you want for your site yet, generate SPACE ID and ACCESS TOKENS in Contentful by following these instructions.

image of API site list options in Contentful

You’ll need to use the same environment variables in the gatsby-config.js file, Gatsby Cloud, and Contentful. The following screenshot shows what the environment variables look like in Contentful.

image of Space ID and Cloud access token APIs highlighted in Contentful

Copy and paste the following into the Preview and/or Builds Environment Variables section:

  • Contentful Space ID value to the CONTENTFUL_SPACE_ID environment variable field in the Gatsby Cloud dashboard.

  • Contentful Preview API access token value to the CONTENTFUL_ACCESS_TOKEN environment variable field in the Gatsby Cloud dashboard

  • Add the CONTENTFUL_HOST key and set the value to

If the above three steps are a little confusing, it’s because the names of the environment variables vary across platforms. This table shows what the environment variables are called in each platform.

What it’s called in gatsby-config.js fileWhat the key is called in Gatsby CloudWhat value to enter in Gatsby Cloud
We recommend CONTENTFUL_SPACE_ID, but you could call it anythingMust match the environment variable name in gatsby-config.jsCopy the Space ID from Contentful
We recommend CONTENTFUL_ACCESS_TOKEN, but you could call it anythingMust match the environment variable name in gatsby-config.jsCopy the Content Preview API - access token from Contentful
We recommend CONTENTFUL_HOST, but you could call it anythingMust match the environment variable name in

Select Next

Adding more environment variables

You can add and remove as many environment variables as you want. The previous section focuses only on the variables that are required for Gatsby Cloud to integrate with your CMS.

Webhooks: Configuring your Gatsby site to work with Gatsby Cloud

Setting up a webhook in Contentful

To make a connection between Contentful and Gatsby Cloud for your site, you’ll need to configure a webhook in Contentful so that content changes can be pushed to Gatsby Cloud.

You can add and edit necessary webhook information in two places in Gatsby Cloud:

  • During the “Create a new Site” process
  • After setting up an instance, on that instance’s Settings page

Contentful documentation on webhooks

Adding a webhook

In “Create the instance” we created a Gatsby Cloud instance which exposed a webhook. We’ll use that exposed webhook now.

Navigate to your Gatsby Cloud instance, and press “Site Settings.” Copy the Webhook on this page.

Copying the webhook URL

Open Contentful and select Webhooks from the Settings dropdown menu

Settings dropdown in <span children={props.cmsTitle} /> with Webhooks option highlighted

Select Add Webhook

Image of add webhook button highlighted

Name your Gatsby Cloud webhook. Leave the URL setting to POST and paste the webhook link you copied from the Gatsby Cloud dashboard. You can leave the Triggers section set to Trigger for all events. image of webhook details page

Click Save to save these changes. If you don’t click save and attempt to navigate to another page in Contentful, Contentful will prompt you to save the information.

Adding the Gatsby Preview button to Contentful

To make it easy for team members working in Contentful to launch Gatsby Preview and to make previews a lot faster, install an extension to enable an “Open Preview” link in the Contentful UI using the doc ”Add the Gatsby Preview Extension to Contentful“.

Contentful Preview button in the sidebar


Now, when you change any copy or content in Contentful, Gatsby Cloud should be up to date with your changes.

© 2020 Gatsby, Inc.