Managing multiple environments

Space environments are entities within a space that allow you to create and maintain multiple versions of the space-specific data, and make changes to them in isolation.

domain model

By default, every space has one environment, called master. Additionally, multiple sandbox environments can be created. Sandbox environments start out as exact copies of the master environment. Environments are made up of the content model, content, and media. Additionally, locales and UI extensions can be altered per environment. When making changes to any of the mentioned entities in any environment, including master, the data in all other environments isn’t affected and stays the same.

API keys are bound to a single space. However, they can be configured to only grant access to specific environments.The same applies to webhooks—with the exception that they only trigger on changes within the master environment.

The two main differences between the master environment and sandbox environments are:

  • Master can’t be deleted and the name can’t be changed
  • Requests from the Content Delivery API (CDA) to sandbox environments aren’t cached and shouldn’t be used in production

Applying changes from sandbox to master

If you intend to apply the changes you make in sandbox environments to master you have to use the Contentful Migration CLI to make the changes and also to migrate them to master.

Access to environments

Permission to manage both environments as a whole and the data they contain is role-based and space-specific. The Administrator role has access to all environments within a space and can create, read, update, and delete sandbox environments. All other roles only have access to the master environment. To them, it appears as any of the entities and settings listed above are direct children of the space.

Space environments in the web app

Depending on the role of a user, environments can be managed and the data they contain can be viewed and altered in the web app. Note that changes in sandbox environments made in the web app cannot be applied to master, since it doesn’t use the Contentful Migration CLI.

Common uses for space environments

Local development

Once your project is up and running, you’ll likely still iterate on it, extend it, and ship improvements. If this is the case, using space environments can supplement your local development. You can create a new environment based on the current state of master and hook up an instance of your application that’s running locally. Then you’ll be ready to make changes to your data and settings.

Editors can make changes to the master environment, while developers work in the development environment.

As soon as your changes are ready for production, you can apply your migrations from the development to master. After that, you can safely delete the development environment.

local development environments

Staging / QA

With space environments, it is possible to set up environments and keep them running alongside the master. An example of this can be for staging and QA. If you create staging or QA environments, these aren’t intended to be used for development—but rather as checkpoints. These can be used before applying changes to the master environment or deploying to your production environment.

Similar to our local development example, developers can work on a development environment that’s created directly from master. Once they’ve finished, the changes are applied to the QA environment. This allows QA engineers to perform manual and automated tests on those changes. If the tests pass successfully, the changes are then applied to staging, allowing for final testing in an environment that mimics production.

staging qa environments

Continuous integration

In an environment that relies heavily on automated testing, environments can be created programmatically and just for the duration of a test. Once it has successfully passed, the environment is deleted.

Space environments enable continuous integration by allowing you to create a template space. This template space maintains the exact state you need to run your tests. Because environments are meant to be used as temporary entities for isolation, you don’t need to run any clean-up tasks. Instead, just delete and recreate a new environment for every test.

ci environments

Editorial workflows

Since space environments is a feature built mainly for developers, we recommend not to use it to cover editorial workflows. As described above, changes made in the web app cannot be applied back to master, therefore elaborate workaround would have to be implemented to mimic an experience editors are used to.

Next steps

Not what you’re looking for? Try our FAQ.