Connecting to Contentful Manually

This guide will show you how to connect your Gatsby Cloud site to Contentful via manual configuration.

Prerequisites

This guide assumes you already:

• have a Gatsby project in a GitHub repository
• have a Contentful space with a content model and content that your Gatsby project understands
• are familiar with how to create a Gatsby Cloud site from a repository

If you are starting a Gatsby project from scratch, check out the Create a Site from a Template tutorial instead.

1. Generate Contentful API Access Tokens

First, you need to generate two access tokens:

• Content Delivery API Access Token (for Production Builds)
• Content Preview API Access Token (for CMS Previews)

In your Contentful space, go to Settings API Keys.

On the Content delivery / preview tokens tab, click the Add API Key button.

Give the API Key an appropriate name and description. You will need the space ID and the access token values in step 2. Click Save.

2. Configure Environment Variables

In Gatsby Cloud, start creating a site using the Import from a Repository flow. Once you reach step 5, "Configure Environment Variables," add the Build and Preview variables for your API keys and space ID as specified in the tables below.

Build Variables

Preview Variables

Note, the keys for these variables will depend on the names you use in your Gatsby project. The ones above are based on gatsby-config.js from Contentful's starter-gatsby-blog. Environment variables can also be configured via Site Settings General Environment variables if your site was previously created.

3. Configure Webhooks

Next, go to the webhook settings for your Gatsby Cloud site and make note of the Build and Preview webhooks. You will need this information for configuration in Contentful.

In Contentful, go to Settings Webhooks, then click the Add Webhook button in the top right corner.

Configure your Build webhook as follows.

1. Provide an appropriate name for your webhook
2. Set the URL request type to POST
3. Enter your Build webhook URL in the URL text field
4. Select the specific events that will trigger a Production Build in Gatsby Cloud (optional)
5. Click Save

After you save your webhook, create another webhook and repeat the above steps for your Preview Webhook. You should have two webhooks, as shown below.

4. Finish

With that, everything is properly configured, and your Gatsby Cloud site will trigger Production Builds and CMS Previews when your content changes. You may also want to install the Contentful Preview Extension to see your CMS Previews directly from Contentful.