Connecting to Contentstack

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

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

Setting up a Contentstack and Gatsby site

First, you’ll need a Gatsby site that’s pulling source data from a Contentstack project via the gatsby-source-contentstack plugin and its source code needs to live on GitHub. If you haven’t set that up yet, try using the gatsby-starter-contentstack starter.

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 Contentstack 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.

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

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.

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

Create the instance

Manual Setup

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

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 Contentstack.

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:

1. In your Contentstack account, select your site Stack and navigate to Settings using the gear icon in the menu. Select “Environments”.

2. Create an environment named “Preview”, and omit the Base URL for now. It will be filled in later.

3. Navigate to Settings using the gear icon again and select “Tokens”.

4. Create a new token, give it a name and add it to the scope for the “Preview” environment.

5. After creating the token you will see an API token and a Delivery Token. You will add these values as environment variables in Gatsby Cloud. You can add these as environment variables for Preview, Builds, or both.

This matches the gatsby-config.js of the site:

module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-contentstack",
      options: {
        api_key: process.env.CONTENTSTACK_API_KEY,
        delivery_token: process.env.CONTENTSTACK_DELIVERY_TOKEN,
        environment: process.env.CONTENTSTACK_ENVIRONMENT,
      },
    },
  ],
};

Select Next

Select Next and wait for the first preview instance to be created.

Configuring Cloud Webhooks

In Contentstack:

• Navigate to Settings using the gear icon and then to “Webhooks”.
• Select “create new webhook.” In Gatsby Cloud:
• Navigate to the Settings for your Gatsby Cloud instance.
• Copy the webhook URL, navigate back to Contentstack webhook, and paste the webhook URL into the field labelled “URL to notify *“.

In Contentstack, there are options to add webhook responses to certain events. Add all the options you’d like!

A best practice is to add webhook responses for nearly everything you can. For example, select any content type, asset, or entry and add responses for any options available, such as create, update, delete, successful publish, and unsuccessful publish.

Note that you have a webhook for your both Preview and Builds in Gatsby Cloud. You may want to set up separate webhooks in Contentstack using different event rules.

Configuring the Preview Environment

After your Preview instance is created, copy the Preview instance URL. Then navigate to your Contentstack stack’s setting (gear icon), navigate to “Environments”, edit the preview environment, and paste the Gatsby Preview URL as the base URL.

Testing Gatsby Preview instance

When you publish changes to your content in Contentstack, your Gatsby Preview instance should update quickly.