Promoting schema changes to your master environment can put production content at risk. This doc covers two workflows for promoting changes safely: applying an isolated migration directly, or staging changes in a third environment before promotion.

#Why work with multiple environments

After you launch a Hygraph project into production, you'll continue improving it. Many improvements require schema changes, since your API's data and shape evolve with new requirements. Applying a schema change directly to your master environment affects your production websites or apps immediately, which puts your business at risk.

Hygraph supports multiple environments so you can iterate on your schema safely before finalizing a content model. An environment is a full copy of your project. Every project starts with a master environment, and your API endpoint reflects it directly.

You can find your master environment API endpoint in Project settings > Access > API Access > Endpoint > Content API. Here's the endpoint for a master environment:

Master environment endpoint example

#Set up a development environment

To create a new environment cloned from your master environment:

1. Go to Project Settings > Environments.

2. Select the environment you want to clone from.

3. Click Clone.

   Clone master environment button in Environments screen

4. Complete the clone form:

   • Display name: Set the environment name.
   • Endpoint alias: Auto-completes from the display name.
   • Accent color: Set the environment's accent color.
   • Description: Add a description for the environment.
   • Clone with content: Clone existing content and assets into the new environment. Recommended if you want to test your development environment with real content.
   • Webhooks: Clone your project's webhooks into the new environment. The webhooks will be initially deactivated in the cloned environment. Clone new environment from Master Environment

5. Click Clone to create the environment. Cloning can take time, depending on your project's size.

You now have a clone of your master environment to experiment on without affecting production.

Switch between environments using the environment dropdown in the top bar.

Project environments

#Content changes made during development

Building a new feature takes time, sometimes days, weeks, or months before it ships.

During that time, editors keep working in your master environment. Their changes exist only there. Your cloned development environment stays at the state it was cloned from, so promoting it to master would revert content back to that point, undoing everything editors added since.

To promote both your latest schema and your latest content, use one of these workflows:

• Isolate changes and apply them to production
• Use a third environment

#Isolate changes and apply them to production

This workflow applies a set of changes from your development environment to your master environment, as a controlled migration. It requires you to:

1. Start a content freeze on your master environment. Since this workflow applies changes directly to master with no buffer environment, freezing content is what protects in-progress editor work here.
2. Make your changes and test them.
3. Use the Management SDK method to isolate the changes and then apply those changes to production directly.
4. Lift the content freeze once the migration completes.

This workflow is generally safe: running the changes as a single migration means they succeed or fail as a whole, not individually, which reduces errors. If any step fails, Hygraph undoes all changes automatically.

#Use a third environment

Promoting environments flowchart

This workflow takes more steps, but it's the safest option. It requires you to:

1. Make your changes and test them.
2. Isolate your changes. Use environment diffing to do this, or find and isolate them yourself if you kept track of them in code.
3. Start a content freeze on your master environment. This prevents editors from creating, editing, or publishing content while you promote staging to master.
4. Clone a third environment named staging from master, right before deploying your feature. Cloning close to deployment time means staging carries master's most recent content.
5. Apply the changes you've made in your development environment to staging too. Use the Management API, as shown here. For small schema changes, like deleting or renaming a field, applying them manually may be more practical.
6. Run tests on your staging environment to confirm 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 Promote the development environment to master for details.
8. Lift the content freeze. Editors regain the ability to save and publish immediately.

If you run into issues with this method, roll back by promoting the old master environment to master again. This may require rolling back your frontend too.

#Promote the cloned environment to master

Once you've made all the necessary changes to your application's codebase, promote the cloned environment to become the new master environment. Click Promote on the cloned environment, in Project settings > Environments.

Promoting the Development Environment to Master

You need to rename the old master environment to avoid a naming clash. Filling in New display name auto-fills New API ID.

Promoting the Development Environment to Master

Click Promote to confirm. Hygraph renames the cloned environment to master, and it becomes your master environment from that point on.

After promoting, deploy your code changes so your production websites or applications match the newly promoted environment. To minimize downtime, automate promotion and deployment in a CI/CD pipeline using the Management API or SDK.

#Tokens and environment promotion

Permanent Auth Token

Tokens hold two kinds of information: an ID and the environment it's associated with (master, staging, development).

To see this yourself, copy a token from your project and paste it into jwt.io. Under Payload: data on the right, you'll find the environment your token targets.

Permanent Auth Token

To keep a token working after you promote an environment, create it in your master environment first, then clone that environment to set up your development environment.

Cloning an environment clones its tokens too, so the new environment's tokens share the same internal ID as the originals. After promotion, these tokens keep working, because the environment and the ID still match.

#Related docs

• Management SDK: Apply schema changes programmatically.
• Environment diffing: Isolate schema changes between environments.
• Environments API reference: Manage environments through the API.