Use environments
Enterprise plans
After Setting up environments for a Space, you can determine which models and content entries are synced to your main environment.
An environment is a clone of your main environment that you use to test changes, such as new models, content, or layouts, before they go live. Models and content in an environment can be linked to their counterparts in the main environment, which keeps them in sync automatically.
Prerequisites
To get the most out of this tutorial, you should have already have the following:
- Builder Admin permissions in a space with an Enterprise plan
- More than one environment
Sync environments with Live Sync
With Live Sync, models and content are by default linked across environments. Linked models and content sync in real time so if you update a model or content entry in the parent environment, the linked copies in other environments reflect those changes.
Sync statuses
Every model and content entry in an environment shows a sync status:
- Linked: The item automatically mirrors changes made to the corresponding item in the main environment.
- Unlinked: The item has diverged from the main environment, usually because someone edited it directly in the environment or turned off Live Sync for it. It no longer receives automatic updates.
An item can also show as Not present in parent space. This means it was created directly in an environment and has no counterpart in the main environment at all.
How items become unlinked
Editing an item in an environment unlinks it automatically. When you edit a model or content entry directly in a child environment, Builder turns off Live Sync for that item and its status changes from Linked to Unlinked.
This is intentional: once you've customized something for testing, Builder stops overwriting your changes with updates from the main environment. You don't need to turn off Live Sync manually first.
You can also turn off Live Sync manually for a model or content and work on it independent of your main environment. Then you can push your changes to the main environment when you're ready.
Working with unlinked items
Unlinked items ignore changes made in main. If you edit a model or content entry in the main environment and the environment copy is already Unlinked, nothing happens to the environment copy. It stops listening for updates from main entirely, and stays that way until you re-link it or resync the environment.
To bring an unlinked item back in line with main, you can push it to the main environment, which re-links it, or turn Live Sync back on, which overwrites any unpushed changes.
Live Sync is one-way
To get changes from a child environment to the main environment, see Pushing changes from a child environment.
The following diagram shows that Live Sync only goes one way, from the main environment to child environments.
Make sure to manually migrate webhooks so that you can ensure that the environment-specific URLs are correct.
Turn off Live Sync for a model
- Navigate to an environment, by either clicking to dropdown at the top of your Space's page or by going to Settings and clicking the Enter link next to your environment of choice.
- In the environment, go to Models.
- Click on the Model you'd like to unlink.
- On the upper right of the Model, click the down arrow next to the Linked indicator and select Turn Off Live Sync.
- In the confirmation dialogue that opens, click the Turn Off Live Sync button. The Linked indicator changes to Unlinked.
The following video demonstrates turning off Live Sync for a model.
Turn on Live Sync for models
- Navigate to an environment, by either clicking to dropdown at the top of your Space's page or by going to Settings and clicking the Enter link next to your environment of choice.
- In the environment, go to Models.
- Click on the Model you'd like to unlink.
- On the upper right of the Model, click the down arrow next to the Unlinked indicator and select Turn On Live Sync.
- In the confirmation dialogue that opens, click the Turn Off Live Sync button. The Unlinked indicator changes to Linked.
The following video demonstrates turning on Live Sync for a model.
Turn off Live Sync for content
You can turn off Live Sync to work on content and models independent of your main environment. Then you can push your changes to the main environment when you're ready.
To turn off Live Sync for content, do the following:
- Navigate to an environment, by either clicking to dropdown at the top of your Space's page or by going to Settings and clicking the Enter link next to your environment of choice.
- In the environment, go to Content.
- Click on the content entry you'd like to unlink.
- Within the menu on the left, click the down arrow next to the Linked indicator and select Turn Off Live Sync.
- In the confirmation dialogue that opens, click the Turn Off Live Sync button. The Linked indicator changes to Unlinked.
The following video demonstrates turning off Live Sync for a content entry.
Turn on Live Sync for content
- Navigate to an environment, by either clicking to dropdown at the top of your Space's page or by going to Settings and clicking the Enter link next to your environment of choice.
- In the environment, go to Content.
- Click on the content entry you'd like to link.
- Within the menu on the left, click the down arrow next to the Unlinked indicator and select Turn on Live Sync.
In the confirmation dialogue that opens, click the Turn On Live Sync button. The Unlinked indicator changes to Linked.
When you turn on Live Sync, all unpushed changes in the child environment are overwritten. If you want to keep your changes in the child environment, you must push to your main environment first.
The following video demonstrates turning on Live Sync for a content entry.
Turn off Live Sync for an environment
In addition to turning off Live Sync for content and models, you have the option of turning Live Sync off for a whole environment.
Note that when Live Sync for an environment is turned off:
- Automatic, live synchronization stops for new content. Existing content continues to sync.
- Changes in the main Space no longer sync automatically to the child environment where Live Sync has been disabled.
To turn off Live Sync for an environment:
- Enter the environment where you want to turn off Live Sync.
- Go to Settings.
- Go to Advanced Settings, then Advanced.
- Click the toggle for Enable Environment Live Sync. This turns off live sync between main and the environment that you are in.
The video below shows toggling Enable Environment Live Sync off within Settings:
Push changes from a child environment
Pushing, which is a manual process, gives you full control over when and how your changes are propagated so that you can carefully review updates before pushing them to the production environment.
Pushing is a manual process of copying updates in the following ways:
- from a child environment to the main environment
- from a child environment to another child environment
If you push unlinked content to the main environment, Builder links the two environments. If however, you push from one unlinked sibling environment to another, the environments remain unlinked.
If you create or edit content or models in a child environment and want those changes in main, you must push in order of dependency:
- Push all changed models.
- Push dependent content, such as Symbols.
- Push the content.
You have to manually push changes from a child environment to the main environment—Builder does not push automatically from child environments to main.
The following diagram shows that pushing goes from a child environment to another child environment or to main:
Push model changes
When you have an unlinked model with changes that are ready for the main environment, you can push them from a non-prod environment to the main or a sibling environment.
Note that if more than one person is working on a model and someone pushes the changes in that content entry, all changes by all users are simultaneously pushed.
If you push unlinked models to the main environment, Builder links the two environments. If however, you push from one unlinked sibling environment to another, the environments remain unlinked.
- Navigate to an environment, by either clicking to dropdown at the top of your Space's page or by going to Settings and clicking the Enter link next to your environment of choice.
- In the environment, go to Models.
- Click on the Model you'd like to edit.
- Edit the model.
- On the upper right of the Model, click the down arrow next to the Unlinked indicator and select Push to
environment. - In the confirmation dialogue that opens, click the Yes, Push Now button. Notice that the Unlinked indicator changes to Linked.
The following video demonstrates pushing changes from a Staging environment to the main environment.
Blocked pushes
If an item is unexpectedly still marked Linked, for example, due to an orphaned-content scenario, the push flow will refuse to push it.
Builder assumes a Linked item already matches main, so there is nothing to push. Manually unlink the item first to promote it.
Push content changes
When you're ready to push content changes, be aware that if more than one person is working on a content entry and someone pushes the changes in that content entry, all changes by all users are simultaneously pushed.
- Navigate to an environment, by either clicking to dropdown at the top of your Space's page or by going to Settings and clicking the Enter link next to your environment of choice.
- In the environment, go to Content.
- Click on the content entry you'd like to push.
- In the Visual Editor, at the top, click the down arrow next to the Unlinked indicator and select Push to Main.
- In the confirmation dialogue that opens, click the Yes, Push Now button. Notice that the Unlinked indicator changes to Linked.
If you've created a model in a child environment rather than your main environment, be sure to push the model first, then the content.
The following video demonstrates pushing content changes from a Staging environment to the main environment within a content entry.
Delete a model or content entry in the main environment
Deleting behaves differently from unlinking. It also behaves differently depending on whether you delete a model or a content entry.
If you delete a content entry in main
If the environment copy is Linked:
- The linked copy in the environment is deleted too.
If the environment copy is Unlinked:
- Nothing happens.
- The copy is left as-is.
If you delete a model in main
If the environment copy is Linked:
- Only the model is removed from the environment.
- Content built on that model is left behind and keeps showing as “Linked,” even though its parent model no longer exists in main.
If the environment copy is Unlinked:
- Nothing happens at all.
- Even the model copy is not removed.
- The environment keeps a fully stale copy.
Deleting a model in main does not clean up the content built on it in linked environments. If you delete a model, check linked environments afterward and manually remove or unlink any leftover content tied to it.
Delete an environment
Deleting an entire environment, rather than just an item inside it, is comprehensive. All models, content, and sync hooks owned by that environment are permanently and automatically removed.
Unlike deleting a model in main, there is no orphaning risk with this action.
Resync an environment
Resync resets an environment by copying all data from the parent Space to create a replica into the child environment, removing any changes made in the child environment before the process.
During the resync, Public API keys, global webhooks, and Space URLs remain unchanged, so you don't have to re-integrate with your app for the new environment.
Customize the resync process by selecting specific items from the parent Space to copy into the child environment while retaining environment-specific data, such as Custom Targeting and Users, in both environments.
To resync an environment:
- Go to to Settings.
- Locate the environment you wish to sync.
- Click the three dots next to the environment name.
- Select Resync from the menu.
- In the panel that appears, select or deselect the items you want to sync.
- Click Resync and confirm your choices.
When performing a resync, you can selectively include:
- Content: Folders, Views, All content entries and models
- Settings: Users, Custom Breakpoints, Custom Roles, Locale and Custom Targeting, Plugins
Settings that sync by default:
- Advanced Settings
- All Fonts
- Code Generation Instructions
- Design Tokens
Example use case:
- Sync all content entries and models from the parent environment while preserving users, roles, and environment-specific data in the child environment.
A video demonstration that shows this process in action:
Quick reference
This table summarizes what happens to an item in an environment, depending on whether it is Linked or Unlinked.
| Action | Linked item | Unlinked item |
Edit in main | Synced down automatically | No change (ignored) |
Edit in an environment | Becomes Unlinked | No change |
Delete content in main | Deleted in the environment | No change |
Delete a model in main | Model removed in the environment. Its content is left behind and still shows as Linked. | No change at all (fully stale) |
Push an environment item to main | Blocked (“already linked”) | Creates or updates the item in main, then re-links it |
Delete an environment | Everything in it is deleted | Everything in it is deleted |
Key takeaway
Environments sync automatically in most day-to-day cases. The exception is deleting a model in the main environment, which does not fully clean up after itself: dependent content in linked environments is orphaned and keeps showing as Linked even though its parent model is gone. If you have deleted a model in main, check any linked environments for leftover content.
