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:
-
Go to Project Settings > Environments.
-
Select the environment you want to clone from.
-
Click Clone.
Clone master environment button in Environments screen
-
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
-
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.
Promoting an environment to master means swapping that environment with master, so it becomes the new master.
To promote both your latest schema and your latest content, use one of these workflows:
#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:
- 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.
- Make your changes and test them.
- Use the Management SDK method to isolate the changes and then apply those changes to production directly.
- Lift the content freeze once the migration completes.
This method has some limitations when it comes to applying schema changes to your master environment. See this document for details.
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 this workflow if you're on the Growth plan, since it includes only two environments total, including master.
It doesn't guarantee against issues, because you're applying a new schema to content that's already changed.
#Use a third environment
Promoting environments flowchart
This workflow takes more steps, but it's the safest option. It requires you to:
- Make your changes and test them.
- Isolate your changes. Use environment diffing to do this, or find and isolate them yourself if you kept track of them in code.
- Start a content freeze on your master environment. This prevents editors from creating, editing, or publishing content while you promote
staging to master.
- 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.
- 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.
- Run tests on your
staging environment to confirm there are no conflicts between the new schema and the updated content.
- 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.
- 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.
This method has some limitations when it comes to applying schema changes to your master environment. See this document for details.
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.
If you haven't already started a content freeze as part of the workflow above, start one now before promoting. This prevents editors from losing in-progress work in the environment being replaced. See Content Freeze.
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.
Coordinate deployment order between your Hygraph project and your frontend applications. When you add models or fields, deploy the Hygraph schema changes first, then the frontend. When you remove models or fields, reverse that order. This prevents your frontend from requesting data that doesn't exist yet.
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.
Pro Tip
Once you promote development to master, the token tied to the development environment stops working.
If you later clone master again to create a new development environment, that token starts working again, since the project ID and environment match once more.