Gatsby Cloud Docs

Getting Started with Gatsby Cloud and DatoCMS

See how to connect Gatsby Cloud with DatoCMS

Table of Contents


First, you’ll need a Gatsby site with a gatsby-source-datocms source plugin pulling data from DatoCMS (list of all services that integrate with Gatsby). The site’s source code currently needs to live on GitHub (other options coming soon).

Signing in to Gatsby Preview

Select Sign in with GitHub. You’ll be asked to authorize the Gatsby Preview 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 a preview instance.

Once signed in, configuring Gatsby Preview with DatoCMS requires several steps that are walked through below.

Creating a preview instance

Once you’ve authenticated with Preview and GitHub, you can create a preview instance from the “Create a new Gatsby Cloud site” page.

We’ll be using the “I already have a Gatsby site” flow to manually integrate our site.

Add my own site

Pick your Gatsby site from the list of GitHub repositories. You can use the search input to narrow down the list.

Gatsby Preview Add a preview instance page

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 Preview works best with Gatsby version 2.1.0 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.

Select branch and directory

Once the branch and directory path are correct, select “Next.”

Create the instance

Integration Step - automatic or manual

If you have already configured an instance of DatoCMS or if you don’t see DatoCMS in the “Automatic Provisioning” list, skip to Manual Integration.

If you do see DatoCMS in the “Automatic Integrations” section, consider using the “Automatic Integration” flow and Gatsby Cloud will set-up your CMS for you!

Automatic Integration

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

As an example, consider the following example using Contentful:

Automatic Integration with Contentful

Finally, press “Create Preview Site” which will create your instance of Gatsby Preview.

Manual Integration

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

Gatsby Cloud will automatically try and detect environment variables necessary in your gatsby-config.js. However — consider adding any additional ones or variables that our automatic detection may have missed. See “Setting up Environment Variables” for more info.

Adding environment variables

Once you’ve added the necessary environment variables, you can press “Create Preview Site” which will create your instance of Gatsby Preview!

Site is Created

After following the “Automatic Integration” or “Manual Integration” flow you now have an instance of Gatsby Cloud configured with environment variables and an provided Gatsby Preview instance you can share with your team. Woo-hoo!

Gatsby Preview Created

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 Preview to authorize your preview instance to pull source data from Sanity.

You will need to add into Gatsby Preview 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 Preview-specific environment variables:

You need a read-only access token from your DatoCMS project. In Gatsby Preview, 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 preview instance to be generated. Now, when you change any copy or content in the CMS, Gatsby Preview should be up to date with your changes.