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 dashboard/sites/create page.

Gatsby Preview Add a preview instance page

Select your organization from the dropdown menu and then select your site using the search bar or from the list.

Preview will list each organization that you have permission for in a dropdown, allowing you to work with more than one organization’s repositories.

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.

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.