Connecting to Kontent.ai

In this tutorial you will discover how to easily integrate a site sourced by Kontent.ai with Gatsby Cloud.

You will

• Create a website using data from Kontent.ai.
• Store its source Code on GitHub.
• Register this Github repository in Gatsby Cloud.
• Configure Kontent.ai webhooks to notify Gatsby Cloud about content changes on preview environment as well as on production.
• Configure preview URLs in Kontent.ai.

What are Gatsby Cloud and Kontent.ai, and why use them together?

Kontent.ai is a headless CMS that content editors can use to edit and publish content. It is a Content-as-a-Service solution that gives enterprises control over their entire content lifecycle in a single unified environment. Gatsby Cloud allows you to integrate your site with Kontent.ai in order to run performant builds and preview content changes made in the CMS before publishing.

Setting up a Kontent.ai and Gatsby site

First, you’ll need a Gatsby site with a gatsby-source source plugin to pull data from Kontent.ai. If you haven’t set that up yet, you can quickly create a new project by using the gatsby starter repository.

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 Kontent.ai 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.

Pick your Gatsby site from the list of GitHub repositories on the left hand side. 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 Kontent.

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 in a specific environment, such as staging and production environments. You must save your environment variables in Gatsby Cloud to authorize your instance to pull source data from Kontent.ai.

First, open your Kontent.ai project and go to Project settings > API Keys. On the API keys screen, copy the values for Project ID and Preview API key (Primary or Secondary).

Then go to Project settings > Localization to get the codenames of your project languages.

You will want to set KONTENT_PREVIEW_ENABLED to true for Preview and false for Builds.

Once you’ve entered your variables, click Save and then Create site.

Go to the Preview tab and wait for the preview instance to be created.

Webhooks: Configuring your Gatsby site to be updated with content changes

To connect Kontent.ai with your Gatsby Cloud instance, you’ll need to configure a webhook in Kontent.ai so that content changes can be pushed to Gatsby Cloud.

You’ll add two webhooks in Kontent.ai: one for Gatsby Preview and another for Gatsby Builds.

Following webhooks could be also added via Management API.

Adding a Preview Webhook

Navigate to your Gatsby Cloud instance and click Site Settings. Copy the Preview Webhook on this page.

In your Kontent.ai project, go to Project settings > Webhooks and click Create new webhook.

Name the webhook and paste the Preview webhook into the URL address field.

In the webhook configuration, select the Create or Update and Delete triggers under DELIVERY PREVIEW API TRIGGERS. Then remove Publish, Unpublish, Delete, Restore, and Create or Update triggers from DELIVERY API TRIGGERS by using the cross next to them. You should end up with the following configuration.

Click Save.

Your Preview webhook is now ready! When you change your content in Kontent, your Gatsby Preview will update!

Adding a Builds Webhook

Navigate to your Gatsby Cloud instance and click Site Settings. Copy the Builds Webhook on this page.

In Kontent.ai, go to Project settings > Webhooks and click Create new webhook.

Name the webhook and paste the Builds webhook in the URL address field.

In the webhook configuration, make sure only the Publish and Unpublish triggers are selected under DELIVERY API TRIGGERS.

Click Save.

Your Builds webhook is now ready! When you publish/unpublish content in Kontent, your Gatsby Builds will update!

Setting the Gatsby Preview Domain for Kontent.ai

To open the Gatsby Cloud preview right from Kontent.ai, you need to configure preview URLs for your content. The following instructions assume you’re using the gatsby-starter sample app.

Navigate to your Gatsby Cloud instance and click Preview. Copy the preview URL.

In Kontent.ai, go to Project settings > Preview URLs and provide the URLs according to your routes configuration.

Now you can open the content preview right from Kontent.ai UI!

Wrapping Up

At this point, you have a Kontent.ai instance configured to best support Gatsby Cloud. Edit content, click the Preview button, and watch it appear live in Gatsby Cloud!