Compare and sync environments
Compare two environments of a project service by service, then stage the variables, settings and releases you pick from one into the other as an ordinary change set.
Environments of one project drift: a variable added in development never reaches production, or a replica count differs for no reason anyone remembers. The comparison lists every difference and lets you stage the ones you choose. Nothing is applied by the comparison itself. What you pick becomes staged changes in the environment that receives them, so it goes through review and, in a protected environment, an approval.
Before you begin
- Both environments must belong to the same project. Preview environments can be compared too.
- Reading a comparison needs any role. Staging needs the
deployerrole or higher, the same as staging each of those changes by hand. - A secret's value is never shown and never copied. See What a comparison shows.
Compare two environments
Open the environment menu in the top bar and select Compare with…. The entry appears when the project has more than one environment. The Compare environments panel opens beside the environment you are in, and its address carries ?panel=compare, so a copied link reopens it.
The Compare with menu names the other side. It starts with the environment a change normally travels from or to: production compares with the environment before it, any other environment compares with production, or with the first other persistent environment when there is no production. Choose another environment to change it, including a preview environment.
Read the groups. Environment variables comes first, then one group per service. A service that runs in one environment only says "Runs in ENVIRONMENT only". Each row shows the value in both environments.
Identical items are hidden and counted. Select Show N identical items to list them.
What a comparison shows
For each service:
- Variables, by key: set in one environment only, different, or the same.
- Release: the release serving in each environment, with its image. Two releases of one image digest count as the same, because release numbers are per environment.
- Settings that an environment can override: replicas and instance size of each process, volume sizes, and Auto-deploy.
- State (running or stopped) and the number of Domains.
- Processes, Release command and Deploy after, read from the live release in each environment.
A secret appears as secret or empty secret, and the row says whether the two environments hold the same value or different ones. The control plane makes that call on the server by comparing digests that exist for one request. The values never reach your browser, and a digest from one comparison cannot be checked against another.
A variable that a nebula.toml sets in either environment shows a nebula.toml tag and cannot be staged. The file owns it: change it there and push.
Stage the differences you pick
Choose the direction with the control beside Compare with: into ENVIRONMENT names the environment that receives the changes. It starts with the environment you opened the panel from.
Tick the rows to stage. Every difference that can be staged is ticked, except removals, which stay unticked. Use Pick all or Clear on a group.
Select Stage N changes into ENVIRONMENT. The button reads Nothing picked and stays disabled until a row is ticked. A toast reads Staged N changes in ENVIRONMENT and says whether applying needs an approval. The panel closes.
The Review N staged changes dialog opens on the receiving environment, switching to it if you staged into the other side. Review the staged changes the way you review any others, then select Deploy N changes. In a protected environment the button reads Request approval, and the panel footer says so before you stage.
Each tick stages one change, tagged by what it does in the receiving environment:
| Tag | What staging does |
|---|---|
| New | Adds a variable the receiving environment lacks, with the value from the other. |
| New · empty | Adds a secret the receiving environment lacks, with an empty value. Fill it in there. |
| Edited | Sets a variable, replica count, instance size, volume size or auto-deploy to the other environment's value. A setting the other environment leaves on its default is reset to the default. |
| Removed | Deletes a variable the other environment does not have. |
| Deploy | Stages the other environment's live release, as a promotion. |
A secret that exists in both environments with different values has no tag and no checkbox. The row says to set it in the environment you want to change.
Syncing never copies domains, stop and start state, processes, the release command or deploy-after. Domains need their own DNS records and certificate. The rest is frozen into each release, so staging Deploy brings the other environment's image and applies it against the receiving environment's own variables and settings.
The empty secret you stage shows the usual hint about empty variables until it is filled in. The hint does not block the deploy.
From the API
Read the comparison (compareEnvironments). left is the environment in the path and right the one in with.
curl -H "Authorization: Bearer NEBULA_TOKEN" \
"BASE_URL/api/v1/environments/ENVIRONMENT_ID/compare?with=OTHER_ENVIRONMENT_ID"Each item has an id, a status (same, differs, left-only, right-only) and, for each direction, intoLeft and intoRight: whether it can be staged, what that does, or why it cannot. Stage the items you picked into the environment in the path (syncEnvironment).
curl -X POST -H "Authorization: Bearer NEBULA_TOKEN" -H "Content-Type: application/json" \
-d '{"from": "OTHER_ENVIRONMENT_ID", "items": ["ITEM_ID"]}' \
BASE_URL/api/v1/environments/ENVIRONMENT_ID/syncBASE_URL is your control plane's public URL, NEBULA_TOKEN an API token, and ITEM_ID an id from the comparison. The control plane works out the edits again at request time and ignores any value you send, so a request can only stage what the comparison shows. If one item has changed since or cannot be staged, the response is a 422 that names it and nothing is staged. On success the response holds the id of your draft change set, how many changes it holds, and whether applying it needs an approval.
Verify
The Review N staged changes dialog shows each staged change with the value it replaces and the value it sets, and secrets show as masked. A value that spans several lines, such as a certificate, is shown whole with its line breaks kept.
Next steps
Roll back or promote a release
Roll a service back to a release that ran before, redeploy its active release, or promote a release's image to another environment, from the console or the API.
Deploy a preview for each pull request
Turn on pull request previews for a project so every same-repository pull request gets its own environment, deployed from its branch and deleted when the pull request closes or goes idle.