Connecting to Cosmic

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

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

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 Cosmic 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 “Create a new Gatsby Cloud site” page.

Use the “I already have a Gatsby site” flow to set up 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 Cosmic in the list, press “Connect” and follow the set-up instructions to link Cosmic with Gatsby Cloud.

Once you’ve authorized Cosmic 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 Cosmic.

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!

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 Cosmic. Gatsby Cloud will fill in Cosmic-specific environment variables automatically when you first configure your site (in the Quick Connect step) by searching your code for used environment variables and pulling the right values from Cosmic.

However, 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.

The following Gatsby Cloud-specific environment variables need to be added if you skipped the Quick Connect with Cosmic:

Cosmic buckets typically have a bucket slug/id as well as a “read key,” both of which can be found Settings - Basic Settings from the Cosmic sidebar.

You will want to grab these values and add them to your Gatsby Cloud instance. A typical naming convention will look like:

Select “Next”

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

Webhook

Cosmic uses a webhook to inform Gatsby Cloud when content changes. Gatsby Cloud will automatically add webhooks to push content changes to your preview instance. Additionally, publishing content will trigger a new build!

You can view webhooks set up for your Cosmic bucket in your bucket’s settings section. If you do not see any webhooks listed with an endpoint from https://webhook.gatsbyjs.com..., you can add them yourself with the following steps.

Wondering what a webhook is or why you need one? Refer to the webhooks reference page.

Manually getting the webhook

Webhooks are automatically generated for every Gatsby cloud site. They can be accessed via your Gatsby Cloud instance - Site Settings - Webhook. There is a webhook to update your Gatsby preview instance, and another webhook to trigger new builds. Copy the applicable webhook as you’ll need it to get Cosmic working swimmingly with Gatsby Cloud.

Adding the webhook to Cosmic

With the webhook URL you’ve just copied, you should now go into your Cosmic bucket and add this webhook for a number of events, notably focusing on creates, updates, and deletes so that your Gatsby Cloud instance stays consistent with Cosmic.

Your webhooks will look something like this when finished: