Connecting to DatoCMS

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

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

Setting up a DatoCMS and Gatsby site

First, you’ll need a Gatsby site with a gatsby-source-datocms source plugin pulling data from DatoCMS. If you haven’t set that up yet, you can quickly create a new project by selecting one of the DatoCMS templates on the Gatsby Cloud get started page.

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 DatoCMS 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 dashboard page.  Then click the "Add a Site" button:

Use the “Import from a git repository” 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

Quick Connect

Find DatoCMS in the list, press “Connect” and follow the set-up instructions to link DatoCMS with Gatsby Cloud.

Once you’ve authorized DatoCMS and selected the appropriate organization, press “Create site” which will create your instance.

Manual Setup

If you'd rather not use Quick Connect follow the steps below:

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

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!

Configure webhooks in DatoCMS

In order to get Cloud builds working, you will need to manually configure a webhook in DatoCMS.

First, login to your DatoCMS project. Navigate to Admin -> Webhooks.

Click the Plus icon to add a new webhook.

Provide the following details in the webhook:

1. A meaningful name for the webhook.
2. The build webhook from your site settings in Gatsby Cloud
3. Setup three triggers:
   • For Records, select the Publish and Unpublish events.
   • For Assets, select the Create, Update, and Delete events.
   • For Models, select the Create, Update and Delete events.
4. Send a custom payload, with this value:

   { 
     "event_type": "{{event_type}}", 
     "entity_id": "{{#entity}}{{id}}{{/entity}}", 
     "entity_type": "{{entity_type}}" 
   }

After you enter the webhook details, click Submit.

Repeat the previous steps and create a second webhook for your previews.

This webhook will be identical with the following 3 changes:

1. Set the name to Gatsby Preview Builds
2. Use the same URL but without the word "publish". https://webhook.gatsbyjs.com/hooks/data_source/<your-site-endpoint>
3. Set the Record Entity trigger to "Create", "Update", and "Delete"

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

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:

You need a read-only access token from your DatoCMS project. In Gatsby Cloud, create an environment variable called DATO_API_TOKEN and enter the value of a read-only API token you generate from your DatoCMS project (Settings > API Tokens > Read-only API Token). You can double check gatsby-config.js and the plugin entry for gatsby-source-datocms for the variable name in case it is different from DATO_API_TOKEN

Select “Next”

Click “Next” and wait for the first cloud instance to be generated. Now, when you change any copy or content in the CMS, Gatsby Cloud should be up to date with your changes.

Gatsby Cloud Preview Extension

To utilize Gatsby Cloud Preview (with the new Content Sync feature), upgrade your DatoCMS source plugin and install the Gatsby Cloud Preview Extension in your DatoCMS project by following these steps.