Connecting to Agility

What are Gatsby Cloud and Agility CMS, and why use them together?

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

Setting up an Agility CMS and Gatsby site

First, you’ll need a Gatsby site with a gatsby-source-agilitycms source plugin pulling data from Agility CMS. If you haven’t set that up yet, you can quickly create a new project by using the agility-gatsby-starter and signing up for an account at agilitycms.com.

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 Agility CMS 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 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

Manual Setup 

First, click “Skip this step” to configure Agility CMS.

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 Agility CMS.

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:

In your Agility CMS account, on the Getting Started page, scroll down to “Pick a framework to kick-start your development!” and click on “API Keys”.

Inside of this modal, click on “Show API Keys”.

You will need to grab the following values from this window:

• Instance GUID
• Live API Key
• Preview API Key

These values will map to the following environment variables in Gatsby Cloud (assuming you are using the agility-gatsby-starter or a similar configuration):

In the Gatsby Cloud Dashboard, the Instance GUID (AGILITY_GUID) will be the same for both Preview and Builds environments.

You will want to set AGILITY_API_ISPREVIEW to true for Preview and false for Builds.

And you will want to use the unique Preview / Live API Keys you grabbed from Agility CMS for the AGILITY_API_KEY setting. Use the Preview API Key for Gatsby Preview, and Live API Key for Gatsby Builds.

Click Save once you’ve entered you’re variables

Select Create Site

Select Create Site and wait for the first preview instance to be created.

Webhooks: Configuring your Gatsby site to work with Gatsby Cloud

Setting up a webhook in Agility CMS

To make a connection between Agility CMS and Gatsby Cloud for your site, you’ll need to configure a webhook in Agility CMS so that content changes can be pushed to Gatsby Cloud.

You can add and edit necessary webhook information in two places in Gatsby Cloud:

• During the “Create a new Site” process
• After setting up an instance, on that instance’s Settings page

You’ll set up two webhooks in Agility CMS: one for Gatsby Preview, and one for Gatsby Builds!

Agility CMS documentation on webhooks

For full documentation on setting up webhooks in Agility CMS, see their webhook documentation.

Adding a Preview Webhook

Navigate to your Gatsby Cloud instance, and press “Site Settings.” Copy the Preview Webhook on this page.

Open Agility CMS, go to Settings the settings page. Select Web Hooks from the Customization / Development Menu

Click the plus sign to add a new webhook for Preview

Paste the Preview webhook copied from the Gatsby Cloud Dashboard

Check the following boxes:

• Receive Content Publish Events
• Receive Content Save Events
• Enabled

Click Save

Your Preview webhook is now ready! When you save or publish content in Agility, your Gatsby Preview will update!

Adding a Build Webhook

Navigate to your Gatsby Cloud instance, and press “Site Settings.” Copy the Build Webhook on this page.

Open Agility CMS, go to Settings the settings page. Select Web Hooks from the Customization / Development Menu:

Click the plus sign to add a new webhook for Preview:

Paste the Builds webhook copied from the Gatsby Cloud Dashboard

Check the following boxes:

• Receive Content Publish Events
• Enabled

Click Save

Your Build webhook is now ready! When you publish content in Agility, Gatsby Cloud will now build and deploy your site!

Setting the Gatsby Preview Domain for Agility CMS

The final step in configuring Agility CMS and Gatsby Cloud is to make sure that content editors are able to preview their content by clicking the preview button from within the content management system.

Finding the Gatsby Cloud Preview domain

You’ll want to add the URL of the Gatsby Preview instance as a domain in Agility CMS. To find this domain in Gatsby Cloud, go to your Dashboard and click on the Preview tab. The URL will display at the top of this tab:

Copy this URL.

Adding a new domain in Agility CMS

In your Agility CMS dashboard, click on Settings in the Menu, and then find Domain Configuration below Site Configuration.

Click on “Website” to edit the settings, and then the plus sign to add a new domain.

Name your new domain something like “Preview”, and for the Domain URL past the Preview URL you copied from Gatsby Cloud. Also check the “Preview Domain” checkbox. This setting will make it so that clicking “Preview” on an Agility CMS entry will open the appropriate page in your Gatsby Preview.

Click Save.

Wrapping Up

At this point, you now have an Agility CMS instance configured to best support Gatsby Cloud. Edit content, click the Preview button and watch it appear live in Gatsby Cloud!