# Work with multiple environments

Promote schema changes safely across environments without losing content, using isolated migrations, a third environment, or a content freeze.

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](https://hygraph.com/images/docs/user-guides/multiple-environments/multiple-environments-master-env-endpoint.png)

## 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](https://hygraph.com/images/docs/user-guides/multiple-environments/multiple-environments-clone-master-button.png)

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](https://hygraph.com/images/docs/user-guides/multiple-environments/multiple-environments-clone-from-master.png)

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](https://hygraph.com/images/docs/user-guides/multiple-environments/multiple-environments-environments.png)

## 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.

**Warning:**

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](https://hygraph.com/docs/developer-guides/project/multiple-environments#isolate-changes-and-apply-them-to-production)
- [Use a third environment](https://hygraph.com/docs/developer-guides/project/multiple-environments#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](https://hygraph.com/docs/developer-guides/project/content-freeze#configure-a-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](https://hygraph.com/docs/api-reference/management-sdk/management-sdk-batchmigration#generate-a-diff) and then [apply those changes to production directly](https://hygraph.com/docs/api-reference/management-sdk/management-sdk-batchmigration#apply-schema-changes).
4. [Lift the content freeze](https://hygraph.com/docs/developer-guides/project/content-freeze#lift-a-freeze-early) once the migration completes.

**Warning:**

This method has some limitations when it comes to applying schema changes to your master environment. See [this document](https://hygraph.com/docs/api-reference/management-sdk/management-sdk-batchmigration#how-schema-changes-affect-the-target-environment) 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.

**Warning:**

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](https://hygraph.com/images/docs/user-guides/multiple-environments/multiple-environments-promoting-envs-flowchart.png)

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](https://hygraph.com/docs/api-reference/schema/environment-diffing) to do this, or find and isolate them yourself if you kept track of them in code.
3. [Start a content freeze](https://hygraph.com/docs/developer-guides/project/content-freeze#configure-a-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](https://hygraph.com/docs/api-reference/schema/environment-diffing#3-apply-schema-changes). 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](https://hygraph.com/docs/developer-guides/project/multiple-environments#promote-the-cloned-environment-to-master) for details.
8. [Lift the content freeze](https://hygraph.com/docs/developer-guides/project/content-freeze#lift-a-freeze-early). 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.

**Warning:**

This method has some limitations when it comes to applying schema changes to your master environment. See [this document](https://hygraph.com/docs/api-reference/schema/environment-diffing#environment-diffing-limitations) for details.

## 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**.

**Warning:**

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](https://hygraph.com/docs/developer-guides/project/content-freeze#configure-a-freeze).

![Promoting the Development Environment to Master](https://hygraph.com/images/docs/user-guides/multiple-environments/multiple-environments-promote-to-master.png)

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](https://hygraph.com/images/docs/user-guides/multiple-environments/multiple-environments-promotetomaster-screen.png)

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.

**Warning:**

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.

### Tokens and environment promotion

![Permanent Auth Token](https://hygraph.com/images/docs/user-guides/multiple-environments/multiple-environments-token.png)

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 [<b>jwt.io</b>](https://jwt.io/). Under `Payload: data` on the right, you'll find the environment your token targets.

![Permanent Auth Token](https://hygraph.com/images/docs/user-guides/multiple-environments/token-audience.png)

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](https://hygraph.com/docs/developer-guides/project/multiple-environments#set-up-a-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.

## Related docs

- [Management SDK](https://hygraph.com/docs/api-reference/management-sdk/management-sdk): Apply schema changes programmatically.
- [Environment diffing](https://hygraph.com/docs/api-reference/schema/environment-diffing): Isolate schema changes between environments.
- [Environments API reference](https://hygraph.com/docs/api-reference/basics/environments): Manage environments through the API.