Guide / Test and run
Drift, promote and protected environments
Compare what an environment has deployed with the files in your project, deploy only what changed, take what runs on dev to prod, and put a lock on an environment that nobody should deploy to by accident.
What it is
An environment is a profile of penstock.yaml that sets its own deployment.url, or the plain deployment section. Drift reads the latest definitions of an environment, compares them with the local files and says, per resource, how the two differ. Promote takes exactly what one environment runs to another. Both work on Camunda 7 and Camunda 8.
| Part | Plan |
|---|---|
penstock drift and the Drift screen, for one environment | Free |
Comparing two environments with --against | Pro, Team in a pipeline |
penstock deploy --only-changed and "Only what changed" | Free |
penstock promote, a dry run included | Pro, Team in a pipeline |
deployment.protected with --confirm | Free |
The approval record --approve-file, checked in a pipeline | Team in a pipeline |
See the drift
penstock drift --env prod
penstock drift --env prod --against staging --format json
The content on both sides is compared after the same normalisation: whitespace, attribute order, comments and the order of incoming and outgoing references do not count. Each resource gets one state.
| in sync | The engine has what the file says. |
| local ahead | The file changed since the last deploy to this environment, and the engine did not. |
| engine ahead | Someone changed the engine, and your file has not changed since the last deploy. |
| differs | Changed on both sides, or there is no deploy record to tell which came first. |
| only local | The file is not on the engine. |
| only on the engine | The engine has a resource with no file in the project. |
Forms are not read from an engine and are not compared. The answer holds names and hashes, never a credential.
The exit code is 0 when everything is in sync, 1 on drift, and 2 when an environment is unknown or cannot be read. That makes it usable as a pipeline step. Without --env it reads the environment that deploy would use by default.
The Drift screen
In Penstock Web it is in the command palette.
Where the Drift screen is, by tool
JetBrains
The Drift screen is in the Tools menu.
VS Code
The command Environments and drift, and a Drift screen with environments as columns and resources as rows.
Command line
penstock drift prints the same states. See drift.
Environments are the columns and resources are the rows. Each cell is a chip with the state and the version the engine has. The drift MCP tool gives an agent the same answer.
.penstock/deployments.json
What was deployed to each environment is recorded in .penstock/deployments.json: a hash and a version for each resource, with no timestamps, so the file does not change when nothing changed. It is the baseline for telling "local ahead" from "engine ahead". Without it Penstock cannot tell which side moved, and says differs. Keep it in git if you want the whole team to see the same states.
Deploy only what changed
In the Deploy popover, Only what changed is on by default. On the command line:
penstock deploy --only-changed src/orders
A resource whose normalised content equals the latest version on the engine is left out and reported as unchanged, skipped. Deploying the same diagram again makes no new version. When the engine cannot be read, everything is sent and the answer says so. See Deployment.
Promote
Pro Team in a pipeline
penstock promote --from dev --to prod --dry-run
penstock promote --from dev --to prod --write --confirm prod
Promote takes exactly what dev runs, meaning the resources whose content there equals the local file, to prod. The plan lists:
- what would be created and what would be updated;
- the secrets and MCP clients prod lacks, by name only, never by value;
- whether the files fit the target's engine version and its element templates;
- the status of the policy pack.
It is a dry run unless you give --write. --write deploys only to an environment declared in penstock.yaml, to its own address, never to an address that came from an environment variable. Exit code 0 means the plan is clean or the deployment was taken, 1 means something blocks it, and 2 means an environment is unknown, not set up or could not be read.
Protect an environment
Mark a profile as protected:
profiles:
prod:
deployment:
url: https://bpm.example.com/engine-rest
protected: true
Deploying or promoting to it then needs --confirm prod, the name typed again. The Deploy popover asks for the name to be typed. Anything but false protects the environment, and the setting is not read from an environment variable.
In a pipeline a protected environment also needs --approve-file: an approval record, a JSON file with the environment, the hash of every file, approvedBy, approvedAt and validUntil. Penstock checks all of these. That check is part of Team in a pipeline. The record is a document kept in git. It is not a signature and not a cryptographic proof, so protect the folder that holds it.
Common problems
- Drift says "differs" for everything.
- There is no deploy record yet. Deploy once to the environment, and the next comparison can tell which side changed.
- Exit code 2.
- The environment is unknown, not set up, unreachable, or its credentials were refused. The message says which. See Profiles.
- Promote refuses with a missing secret.
- The target lacks a secret or an MCP client the diagram names. Add it to the target environment first. See Connections map.
- Deploy to a protected environment asks for a name.
- Type the environment's name, or pass
--confirm <name>. That is the lock doing its job.