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
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
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):
|Value||Environment Variable Name|
|Live API Key||
|Preview API Key||
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
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.
Save once you’ve entered you’re variables
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
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
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.
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!