In this tutorial, you will learn one of the recommended approaches when using multiple environments to ensure safe changes to your production projects while making sure the latest content changes are maintained on environment promotions.
Once you launch a GraphCMS project into production, you will usually work on continuous improvements of your digital product. In some cases however, implementing a new feature means also that you will have to apply breaking changes to your schema, as requirements of the API shape and data will change. But applying such change to your master environment will also break your production websites or apps, which is a risk for your business.
To allow safe iterations on your schema until you develop the final content model for the feature you want to add, GraphCMS supports working with multiple environments. Environments are instances of your project. Think of them as copies of your whole project, or branches similar to Git. Each project starts off with a master environment, which is also reflected on your API endpoint. In the following example, we see the endpoint of our master environment:
Setting up a Development EnvironmentAnchor
To spin up a new environment based on your master environment, head over to the Environments tab in your project settings, select the environment you want to clone from and click the clone button. Provide a name for the new environment and select to copy over also the content, which is recommended if you want to test your development environment with real content. Given the size of your project, cloning may take a few moments. In the following example, we name our new environment "Development". And as you can see, we get a new API endpoint for this environment that ends with /development.
Great! Now we have a clone of your project’s master environment to experiment with schema changes without breaking the schema of our production environment.
In the CMS interface, environments can be switched with the environment picker next to your project avatar.
Promoting the Development Environment to MasterAnchor
Once you have made all necessary changes to your application's code base, simply promote the development environment to be the new master environment. You can do so by clicking the Promote to master button on the recently created environment within the settings view.
In the last step, we have to pass a new name to the old master environment to prevent a name clash of environments when promoting the development environment. Once you confirm, the development environment will be renamed to master and will be your main environment from now on.
In the same turn, deploy your code changes so your production websites or applications are compatible with the newly promoted environment. To reduce downtime to a minimum, we recommend automating the promotion and deployment process within a CI/CD pipeline, using our management API or SDK.
Maintaining Content Changes That Happened While in DevelopmentAnchor
Developing a new feature often requires time. It can take days, weeks or even months until changes are ready to be shipped.
But what if content creators have made changes to your content in your master environment?
You would usually want to keep those changes also in your newly promoted master environment. But at the time of cloning, the content updates didn't even exist, so the content on your cloned development environment is out of date and promoting this environment to master will also mean reverting your content to the time of cloning. To prevent this and making sure that your work will result in both, the latest schema and the latest content at time of promotion, we recommend the following workflow:
1) The key to this is working with a third environment that you just clone from master shortly before you deploy your new feature into production. Let's call this environment staging. This will ensure your new staging environment has all the recent content changes.
2) Apply the changes you've made to your development environment also to your staging environment. Now, to not make this a cumbersome manual process, we recommend coding all your schema changes in a migration file and using the management SDK to apply those schema migrations in one run to your staging environment. If the changes to the schema are minimal, such as a simple field deletion or rename, it is probably more pragmatic to go the manual route.
3) Promote your new staging environment to be the new master environment, containing the most recent content and schema changes.
That’s it! Currently we are developing improvements to simplify this process. So stay tuned!
Learn more about environments in the documentation or follow Jamie's video tutorial here.
