This document discusses 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.

#Reasons for working with multiple environments

Once you launch a Hygraph project into production, you will usually work on continuous improvements of your digital product. In some cases, implementing a new feature means also that you will have to apply changes to your schema, as requirements of the API shape and data will change. But applying such change to your master environment will affect 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, Hygraph supports working with multiple environments. Environments are instances of your project. Think of them as copies of your whole project. 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:

Master environment endpoint example

#Setting up a Development Environment

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.

Clone master environment button in Environments screen

In the following example, we name our new environment "Development". As you can see, we get a new API endpoint for this environment that ends with /development.

Clone new environment from Master Environment

Complete the required information on the screen:

• Provide a Display name for the new environment, the Endpoint alias will be auto-completed as a result. Optionally, you can provide a Description.
• There are two checkboxes at the bottom of the screen:
  • Clone with content: if selected, the existing content and assets will be cloned into the new environment. This is recommended if you want to test your development environment with real content.
  • Webhooks: If selected, your project's webhooks will be cloned. Please note that they will be initially deactivated in the cloned environment.
• Click on the Clone button at the bottom of the screen to create the clone. Cloning may take some time, depending on the size of your project.

Once this is done, you have a clone of your project's master environment to experiment with schema changes without affecting the schema of your production environment.

In the CMS interface, environments can be switched with the environment switch dropdown in the top bar.

Project environments

#Maintaining content changes that happened while in development

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. The issue here is that at the time of cloning, those content updates didn't exist, so the content on your cloned development environment is outdated and promoting this environment to master will also mean reverting your content to the time of cloning.

To prevent this and make sure that your work will result in both, the latest schema and the latest content at time of promotion, we recommend using one of the following workflows:

• Isolate changes and apply them to production
• Working with a third environment

#Isolate changes and apply them to production

In this scenario, you will be applying a set of changes from your development environment to your master environment using a controlled migration. This workflow requires that you:

1. Make your changes and test them.
2. Use the Management SDK method to isolate the changes and then apply those changes to production directly.

This workflow is relatively easy, and generally safe, as running a set of changes as a migration means they will either succeed or fail as a whole instead of individually. This reduces the risk of errors. If any step fails, all changes are undone automatically.

#Working with a third environment

This workflow is a little longer, but it is also the safest. It requires for you to do as follows:

1. Make your changes and test them.
2. Isolate your changes: you can use environment diffing to do this. Alternatively, you may be able to find and isolate the changes because you kept track of them in code.
3. Call out a content freeze.
4. Clone a third environment: The key to this workflow 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.
5. Apply the changes you've made to your development environment also to your staging environment. You can do this using the Management API, as shown here. 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.
6. Run tests on your staging environment to ensure there are no conflicts between the new schema and the updated content.
7. Promote your new staging environment to be the new master environment, containing the most recent content and schema changes. See next section for details.
8. Lift the content freeze.

That's it!

Promoting environments flowchart

#Promoting the Development Environment to Master

Once you have made all the 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.

Promoting the Development Environment to Master

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. Completing the New display name field auto-fills New API ID field.

Promoting the Development Environment to Master

Once you confirm by clicking on the Promote to master button at the bottom of the screen, the Development Environment will be renamed to master and will be your Master Environment from now on.

Following this, 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.

#Tokens and environment promotion

Permanent Auth Token

Tokens hold two kinds of information: an ID and an "audience" that changes depending on the environment (master, development, etc).

To see this for yourself, copy a token in your project and paste it here. On the right, under Payload: data, you will find which "audience" your token is meant for.

Permanent Auth Token

To keep tokens working when you promote an environment, you need to first create them in your master environment. Then you can clone this to set up your development environment.

When you clone an environment, the tokens get cloned too. This means the tokens in the new environment will have the same internal ID as the original. After promotion, these tokens will still work because the "audience" and the ID will still match.

#Resources

• Management SDK documentation
• Environment diffing documentation
• Documentation on environments
• Jamie's video tutorial