John Hodge

How I use Contentful and Gatsby to manage my website

How I use Contentful, Github, Gatsby, and Netlify with my website

Published by on

I’ve been working on updating my website to use a more modern stack. Now that I have it spun up, I’d like to talk a little about how it works from an operational point of view.

Introduction to my stack

My website's content is powered with Contentful CMS, Github, Gatsby, and Netlify. If you’re not familiar with these tools, here’s a quick summary of how I'm using each of them.


  • CMS that supports parallel development of website files and the content model1


  • Code repository for holding my website’s code

  • Project management with automated Kanban boards

  • Ticketing system to capture features, bugs, build process changes, experiments, and other development work that I will prioritize


  • Static site generator

  • GraphQL management, and where I develop components, pages, and templates


  • Static website hosting

How I use Github and Contentful

The way that I use Github and Contentful varies a little depending on the scope of the development work being done. If there’s an impact on the content model, then I’m going to set up Contentful and my Github to accommodate those changes. I'll focus on these kinds of changes throughout this article.

First, let’s talk about how I set up Github.

Github Configuration

I’m regularly adding tickets to my website’s repo when I notice issues or think of new features to add.

I prioritize tickets and when I’m working on an issue that will require changes to the content model, I create two branches.

One is called 'issues{issue_number}' (issue_number is the number of the issue in Github). This branch is where I’ll do most of my development work (this includes work in Gatsby files, Netlify files, and creating Contentful migration scripts).

The other is called 'staging'; this will be where I merge the issue branch.

When I'm working on a ticket that requires changes to the content model, I never merge the issue branch directly into the main branch.

Contentful Configuration

I like to make my Contentful configuration match Github. So, I make environments called 'staging' and 'issues{issue_number}' using the Contentful CLI space environment create command2.

Similar to branches, the 'issues{issue_number}' environment is where I’ll be doing most of my work. This work includes writing and pushing migration scripts up to the environment.

How I use different Contentful environments

There are three main places where development and testing occur. They are, my local device, branch deploys, and preview deploys.

First and foremost, I set up my gatsby-config.js file to receive different environments with variables. Under the gatsby-source-contentful plugin4 object I add the following setting:

environment: process.env.CONTENTFUL_ENVIRONMENT 

Then, I set up the following development and test areas like this:

Local device: This is where most of the development work happens. There’s a lot of testing here too, but a good amount of dev. I use the .env file to set CONTENTFUL_ENVIRONMENT=issue{issue_number},

Branch deploys: This is where I make sure the migration scripts and feature changes are working as expected. I do this in the staging environment in Contentful. In my netlify.toml file, I add the following context setting:


Preview deploys: This is where I do a final confirmation that all my changes are ready to be pushed to production. This preview is generated when I create a pull request from staging to main. Similar to the branch deploys, this is set up using the netlify.toml. This time add the following context setting:


My workflow throughout the process

After I know what ticket I’m going to work on, my workflow has three main parts:

  • Getting environments and branches set up
  • Developing features or fixing bugs
  • Branch cleanup

Get environments and branches set up

This one’s pretty self-explanatory, I make my Github branches and Contentful environments. I also set up my .env and netlify.toml files.

I basically create a safe space to write code so I can mess up without any serious problems. I mess up a lot so this is important. Ha.

Develop changes in issues environments and branches.

I usually handle the content model changes first, then code Gatsby templates against these new content items. That said, I'm not strictly following an order, but I prefer to have content items to develop against.

For example, I added footnotes to my blog post template recently and created a content type for them.

In this case, I think creating the footnotes content type first was key in developing how the ternary function would work on the template to loop through them and add id tags for linking.

Scripting against Contentful has been surprisingly easy. They have a great scripting resource to get started with3. I’ve had to do some tests, delete fields, undo changes, and I could see a situation where I need to delete an environment and start over. Using a development environment makes this process safe and I experience little or no anxiety while working on the content model.

After I have the Gatsby files configured properly, and I have a migration script that works as expected, I merge the issue branch into the staging branch and push the migration up to the staging environment. If all goes well, I open a pull request to merge the staging branch into the main branch and push the migration to the master environment in Contentful.

Before I merge the pull request, I use the deploy-preview functionality in Netlify5 to make sure I didn’t miss any issues.

If everything looks good, I confirm the merge. Jackpot.

Branch cleanup

After I went through the process above, I delete the staging and issue branches from Github and the environments from Contentful.

The development process with this stack

This has been my favorite development process for web development work so far. I feel like making changes to how the CMS captures content is a seamless part of the development process with Contentful. It's been a pleasure to work with, for sure.

While this process was a little confusing at first, I'm hooked now.


  1. Contentful. “CMS as Code.” Contentful, 2021.

  2. Contentful. “Managing Multiple Environments.” Contentful, 2021.

  3. Contentful. “Scripting migrations with the Contentful CLI.” Contentful, 2021.

  4. Gatsby. “gatsby-source-contentful.” Gatsby, 2021.

  5. Netlify. “Introducing Deploy Previews in Netlify.” Netlify, 2021.