Was this page helpful?

Create and deploy content type changes

Goal of the tutorial

The goal of this tutorial is to instruct you on how to make changes to your content model and merge them to production using Contentful toolkit. The tutorial provides a step-by-step instruction, where each step can be accomplished using one of the following options:

  • The developer's UI (Contentful web app and Merge app).
  • Content Management API (CMA).
  • Contentful CLI.
  • Via a CI/CD pipeline — for details, refer to Continuous Integration Tutorial.


Tools and accesses

  • Contentful account.
  • To work with Merge app — Merge app installed.
  • To work with CMA – access to CMA.
  • To work with Contentful CLI — locally installed Contentful CLI and authentication with Contentful CLI.


In your space, set up a master alias and target it to the environment that serves production content.


Training course

Take the training course in our Learning Center to learn how to deploy and roll back changes using the environment aliases: Making risk-free releases and instant rollbacks.

Set up environments and make changes

NOTE: In the flow below, we use an example setup of environments that we refer to as “development” and “release” environments. However, environment IDs are custom and you are free to use ones that work best for you.

The process of creating changes to your content model and deploying them to production is accomplished with the following major steps:

1. Set up a development environment.

Create an environment to be used specifically for development. To create a development environment, clone the target environment of the master alias so you can make and test changes with a latest copy of production data.

Important: When you clone an environment, workflows aren't copied from it to the new environment.
NOTE: To ensure a safe and reliable release, we recommend that you make and test changes in a development environment before moving them to production. This ensures you start with your space’s latest content model and content, and allows you to make changes and test them without affecting what’s in production.

You can create an environment according to one of the following options:

Create and deploy changes 001

2. Make changes to the content model.

Go to your content model and make the necessary changes. You can set up new content types or edit the existing ones by adding or removing fields or changing the existing fields settings.

Learn how to create a new content type or update an existing one:

Create and deploy changes 002

3. Test content model changes.

Test your changes to make sure everything works as expected:

  • Manually — Test changes manually in the web app.
  • Run automation tests — If you work with automated deployment pipelines, verify your changes by running predefined tests.

Create and deploy changes 003

4. Set up a release environment.

The release environment can be used to put together changes from multiple development environments to be reviewed before further moving them to production. To create a release environment, clone a target environment of the master alias to have a fresh copy of production content. To see the options on how to create environments, refer to step 1 of this tutorial.

Important: When you clone an environment, workflows aren't copied from it to the new environment.

Create and deploy changes 004

5. Persist content model changes.

NOTE: This step is optional if you apply changes using the Merge app. In this case, you can persist changes for different purposes, e.g. to later apply them in environments of a different space or to keep a record of the migration.

You can save your changes to use them in any other working setup by generating and downloading the migration file. For example, it can be saved in your GitHub repository to trigger your CI pipeline and run automation tests in other environments.

The migration file can be created according to one of the following options:

Create and deploy changes 005

6. Apply content model changes.

In this step, merge to the release environment the content model changes you created in your development environment, as well as the changes made and tested by other developers in their development environments. Content model changes can be merged to the release environment according to the following options:

Create and deploy changes 006

7. Change alias target.

Change your production alias target to point to the release environment, in which the changes were applied:

Your content model changes are deployed to production.

Create and deploy changes 007

8. Optional: Roll back your changes in case of an error.

If you discover that the deployment breaks the production website or app, you can roll back the changes by switching the production alias to its previous target environment. To see the options on how to change the alias target, refer to step 7 of this tutorial.

Create and deploy changes 008