Connecting to ButterCMS

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

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

Setting up a ButterCMS and Gatsby site

First, you’ll need a Gatsby site that’s pulling source data from a ButterCMS project via the gatsby-source-buttercms plugin and its source code needs to live on a Git Repository. If you haven’t set that up yet, try using the gatsby-starter-buttercms 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 ButterCMS requires several steps that are walked through below.

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

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. Log-in to your ButterCMS account. Hover to your profile icon to access the settings option

2. From the settings menu, you’ll have access to the API Tokens tab

3. This will show your Read API Token (and your Write API Token if you have requested it)

4. You will add these values as environment variables in Gatsby Cloud. You can add these as environment variables for Preview, Builds, or both.

At a minimum, set BUTTER_CMS_TOKEN to your Read API Token.

Select Next

Configuring Cloud Webhooks

Wait for the first preview instance to be created before proceeding.

In Gatsby Cloud:

• Navigate to the Settings for your Gatsby Cloud instance.
• Copy the webhook URL

In ButterCMS:

• Navigate back to your settings and go to the “Webhooks” tab
• paste the webhook URL into the field labelled “Target URL *”
• Click “Save”

Within ButterCMS, there are options to add webhook responses to certain events.

To start, add post.published, page.published, post.delete and page.delete in your  webhooks configuration and target this with your build URL. This will give you notification whenever a blog post or page has been published or deleted.

For your preview URL, add page.draft and post.draft to get notification when a new page or blog post has been saved as draft.

You should end up with the following configuration:

To learn more about ButterCMS Webhooks, checkout the documentation here.

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

For questions about `gatsby-source-buttercms` or the ButterCMS platform, please contact support through your ButterCMS dashboard. Gatsby is unable to provide dedicated support for ButterCMS.