Getting started with Gatsby Cloud and Kontent
Learn how to connect Gatsby Cloud with Kentico Kontent
Table of Contents
In this tutorial you will discover how to easily integrate site sourced by Kentico Kontent with Gatsby Cloud.
- Create a website using data from Kentico Kontent.
- Store its source Code on GitHub.
- Register this Github repository in Gatsby Cloud.
- Configure Kentico Kontent webhooks to notify Gatsby Cloud about the content changes on preview environment as well as on production.
- Configure preview URLs in Kentico Kontent.
Kontent 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 in order to run performant builds and preview content changes made in the CMS before publishing.
First, you’ll need a Gatsby site with a gatsby-source-kontent source plugin to pull data from Kontent. If you haven’t set that up yet, you can quickly create a new project by using the gatsby-starter-kontent-lumen repository. For detailed guidance on working with this starter, see the Getting started tutorial.
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 requires several steps that are walked through below.
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 manually integrate your 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.
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.
Once the branch and base directory are correct, select “Next.”
First, click “Skip this step” to configure Kontent manually.
Gatsby Cloud will automatically try and detect environment variables necessary in your
gatsby-config.js. However — consider adding any additional variables that automatic detection may have 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!
After following the “Automatic Integration” or “Manual Integration” flow you now have an instance of Gatsby Cloud configured with environment variables and a provided Gatsby Preview instance you can share with your team. Woo-hoo!
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.
First, open your Kontent 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.
The language codenames used in the
gatsby-starter-kontent-lumen sample app are
|Value||Environment Variable Name|
You will want to set
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.
To connect Kontent with your Gatsby Cloud instance, you’ll need to configure a webhook in Kontent so that content changes can be pushed to Gatsby Cloud.
You’ll add two webhooks in Kontent: one for Gatsby Preview and another for Gatsby Builds.
Following webhooks could be also added via Management API.
Navigate to your Gatsby Cloud instance and click Site Settings. Copy the Preview Webhook on this page.
In your Kentico Kontent 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.
Your Preview webhook is now ready! When you change your content in Kontent, your Gatsby Preview will update!
Navigate to your Gatsby Cloud instance and click Site Settings. Copy the Builds Webhook on this page.
In Kentico Kontent, 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.
Your Builds webhook is now ready! When you publish/unpublish content in Kontent, your Gatsby Builds will update!
To open the Gatsby Cloud preview right from Kentico Kontent, you need to configure preview URLs for your content. The following instructions assume you’re using the
gatsby-starter-kontent-lumen sample app.
Navigate to your Gatsby Cloud instance and click Preview. Copy the preview URL.
In Kentico Kontent, go to Project settings > Preview URLs and provide the URLs according to your routes configuration.
Now you can open the content preview right from Kentico Kontent UI!
At this point, you have a Kontent instance configured to best support Gatsby Cloud. Edit content, click the Preview button, and watch it appear live in Gatsby Cloud!