Environments and environment aliases best practices

Environments and environment aliases usage

Environments and environment aliases enable developers to update the content model without affecting the production content. You can set up and use your environments and one or multiple environments aliases to help you to:

• Work on your content types changes locally.
• Test content types changes.
• Bring together content types changes done by multiple contributors.
• Apply content types changes to production.
• Roll back to the previous version of your content types in case anything goes wrong.

Read the recommendations below to learn how to use environments and environment aliases for different purposes.

Local development

Use environments for local development to iterate on, extend, and ship improvements to your existing project. You can create a new environment by cloning it from an environment that runs your production content and connect an instance of your application that’s running locally. Then you’ll be ready to make changes to your data and settings.

Staging / QA

Set up environments to test changes without affecting the production content served by the “master” environment or “master” alias. For example, you can create staging and QA environments to test changes before applying them to the “master” environment or “master” alias where your production content is served.

Similar to our local development example, developers can work on a development environment that’s cloned from the “master” environment or the target environment of the “master” alias. Once they’ve finished, the changes are applied to the QA environment. After this, QA engineers can 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 is used for production.

Apply changes from sandbox environments to the “master” environment

You 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 in your “master” environment to apply the same changes.

Continuous integration

For the development pipelines that rely on automated testing, environments can be created programmatically and just for the duration of a test. Once the test has successfully passed, the environment is deleted.

You can programmatically create an environment by cloning an environment where the changes were made and run the automation tests in it. 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.

To learn more about running migrations in environments as part of CI/CD pipeline, refer to Integrating migrations in your continuous delivery pipeline.

Editorial workflows

We recommend editors to work with content in the “master” environment or the “master” alias, while developers work on new features in sandbox environments.

Enabling risk-free releases and instant rollbacks

Your “master” alias should be used to serve your production content. Use it to target your most up-to-date, currently used environment. This content can be accessed according to the following options:

• Specifically referencing environment alias ID: /spaces/<space_id>/environments/master/content_types/…
• Leaving out the environment fragment altogether: /spaces/<space_id>/content_types/…

With an environment alias, you can quickly change an environment that is served from these routes. After that, in case something goes wrong and you need to roll the changes back, simply re-target the environment alias to any previous environment.

Custom aliases

Apart from the “master” alias, you can also create custom environment aliases. These aliases work similarly to the “master” alias in that you can use them to quickly switch which environment is being served to these static pointers. These environment aliases can be used to aid the development process.

For example, you can create environment aliases and give them IDs “development” and “staging”. Developers can always retrieve content from /spaces/<space_id>/environments/development/..., with a space admin re-targeting the “development” environment alias to a different environment to test out a new content model.

Unlike the default “master” alias, custom environment aliases can be given any custom ID.