Creating Contentful backups with Semantic Release

Photo by Steve Johnson on Unsplash

About Contentful and Semantic Release

You may have heard about Contentful or Semantic Release. The first one it’s a CMS focused on API first and the second it’s a fully automated version management and package publishing tool with a lot of personalization capabilities. You might wonder what relationship can have between those, in this article I will explain how we are creating and saving backups of Contentful in Github using Semantic Release in a fully automatic workflow with CircleCI, in Packlink.

This solution can work perfectly if you are using only one production environment in Contentful. You can use this approach and give it a spin (or two) to adjust it to your needs :)

Contentful CLI tools

Contentful created a nice set of tools for exporting and importing content and models. You can use it as a CLI or separately. For this example we will use contentful-export tool it’s already inside Contentful CLI but we want to use it alone for exporting a JSON for our space content, models and assets.

List of things we need to start

We will need two variables, the Contentful space ID and a management token. First let’s get the space id, head to space general settings and you will see it

No matter if you want to create a backup of one environment or another, that ID it’s unique. Also, we are going to need a management token, for this example, we will use a personal access token head to APIs menu:

Generate a new personal token and save it for later.

Node script

Let’s create an isolated node script with the necessary stuff for exporting all content, models and assets from the master environment, later we will put this script in our Semantic Release config.

First install the library:

npm install --save-dev contentful-export

Now create the script:

// script.js
const contentfulExport = require(‘contentful-export’);
contentfulExport({
    spaceId: space-id’,
    managementToken: ‘token’,
    environmentId: ‘master’,
    exportDir: ‘backups’,
    contentFile: ‘environment-backup.json’,
    errorLogFile: ‘error.json’
});

As you can see we are setting an exportDir if you do it make sure the folder exists before executing the script.

And run using node script.js if everything works as expected you will see this output

Take a look to all contentful-export configuration options, maybe you want to enable/disable some.

Semantic Release

At this point you sure heard about Semantic Release or you are using it and want to create new custom flows. If you are the first kind I encourage you to read all semantic documentation about how it works, how to install and configure, etc. In this guide, I will jump directly in to create a new plugin and add it in our semantic flow.

For our example we will save the generated backup in GitHub using @semantic-release/git plugin.

How to create a new a new Plugin

The official documentation explains perfectly how a semantic release plugin works, how we can use the plugin in any release step and pass configuration to it.

For our example we will rely on two steps, the first one verifyConditions will check that both environment variables are present (space id and management token) then we’ll use generateNotes to create and save the generated JSON (at this step the new changelog file it’s generated, so we can assume it’s the step where we create/update files before commit them to git)

I’ve moved the example code into a gists file:

https://gist.github.com/orta-sanz/22870b3664daa933d32e425ece05f576

All steps will be executed, that’s why we created a verified variable, to avoid any errors with contentful-export if there aren’t the required variables.

Add our new plugin to semantic’s flow

First let’s install contentful-export plugin:

npm install contentful-export --save-dev

Let’s assume that you are using release.config.js file to set up all semantic’s config and plugins, create a new folder next to the config file, let’s call it plugins and inside put the plugin’s file we created before. Remember that all plugins follow the same execution order so we need to run our new plugin before semantic git.

As you can see we’ve also updated @semantic-release/git config to include all JSON files generated by our new plugin.

And that’s it, we have created our custom Contentful backup plugin for Semantic Release :)

As I said at the beginning of this guide this approach may not suit you perfectly but you can use it as an example of what can be achieved with Semantic Release and Contentful.