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.

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 aforementioned 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—they can be filtered to trigger only on changes within specific environments.

Please note that for security reasons, any request to an environment using an API key that is not enabled for that environment will return a 404 HTTP status.

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

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. You can whitelist additional roles by allowing them to manage and use all sandbox environments in this space. 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 Contentful migration scripts.

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 should edit content in the master environment, while developers can develop new features in a sandbox environment.

Applying changes from sandbox environments to master

Developers can write scripts in the Contentful Migration DSL so that migrations are reproducible. After testing the execution of those scripts in sandbox environments using the Contentful CLI, you can execute those already-tested migration scripts on master to apply the same changes. Learn how to write migrations scripts by reading this tutorial.

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.

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.

Read our documentation on continous integration and deployment pipelines to better understand these workflows.

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

• Understand the domain model of Contentful
• Read the Space Environments API Documentation
• Learn how to integrate migration scripts and environments into your continuous integration & deployment pipelines
• See how you can evolve your environments programmatically Not what you’re looking for? Try our FAQ.