This guide will explain how executing Contentful migrations against environments fits into a standard continuous delivery pipeline.

When building software, an integral part of delivering new features safely and efficiently is having a continuous delivery pipeline set up. The purpose of the pipeline is to be able to move development changes into production through an automated set of steps that will verify the integrity and quality of the changes.

What the exact steps are depends on your application and environment, but a common scenario looks something like this:

• Build
  • Build your application and verify that the code compiles as expected.
• Test
  • Run automated tests; unit tests; integration tests.
• Deploy
  • Deploy the application to a number of environments. Often to a staging or pre-production environment manually test before deploying to production.
• Test
  • Run automated end-to-end tests against the environments you deployed your application to in the previous step.

Running migrations as part of a CD pipeline

When building applications that leverage Contentful for content delivery, a common need is to replicate model changes across a number of environments. Since the Contentful CLI is distributed as a regular npm package you can easily install and use it as part of your delivery pipeline, ideally just before (or after) you deploy your application. The above-mentioned pipeline would adapt to look something like this:

• Build
• Test
• Migrate
  • Run your migrations to update your content model for the space/environment you will next deploy to.
• Deploy
• Test

Executing migration scripts will prepare your space/environment for the new changes you have made to your application and its content model.

Keep your migrations small

We recommend keeping your migrations as small and as backwards compatible as possible. Since the Contentful CLI executes your migration scripts through incremental API requests, the smaller you make the changes the easier it is to pin point any problems that occur. It is also important to keep in mind that while the migration is running it will affect any application that is currently fetching content from that space/environment. If you introduce breaking changes in your content model there will be a small window between your migration script's execution and the deployment of your application where your application is vulnerable to breaking. This time window can be kept small (or even removed entirely) by trying to not introduce breaking changes and keeping the migration as quick as possible. The technique of avoiding breaking changes is called the "forward-only migration principle" and it is detailed further in "Infrastructure as code".

Next steps

To learn more about the migrations DSL, executing scripts from the Contentful CLI, or the Contentful Environments feature, follow the links below.

• Read the reference documentation of the migrations DSL to get the full details of its capabilities.
• Read about the Contentful CLI
• Read the Environments guide explaining how to get started with Contentful and environments.
• Understand the forward-only migration principle, as explained in the "Infrastructure as code" article.
• View the tutorial on how to implement Contentful migrations on CircleCI.