Gatsby Cloud Docs

Getting started with Gatsby Preview and DatoCMS

Learn how to connect Gatsby Preview with DatoCMS


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 when creating a preview instance.

Adding a preview instance

Once you’ve authenticated with Preview and GitHub, you can add a preview instance from the dashboard/sites/create page.

Gatsby Preview Add a Site page

Pick the repository and site you want to use

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

Note: Repositories must contain one Gatsby project. If the project isn’t in the root folder you can add a path to it. For example, /web. configured at their root to be enabled. Gatsby Preview works best with Gatsby version 2.1.0 and higher.

Add a new site to Preview page with organization drop down and site highlighted

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.

Note: Setting a webhook is not required for all users

Some users don’t need to configure a webhook; skip this step for DatoCMS.

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.