Penstock

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.

Free One environment: free. Comparing two environments and promote: Pro, and Team in a pipeline. Camunda 7 or Camunda 8.

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.

PartPlan
penstock drift and the Drift screen, for one environmentFree
Comparing two environments with --againstPro, Team in a pipeline
penstock deploy --only-changed and "Only what changed"Free
penstock promote, a dry run includedPro, Team in a pipeline
deployment.protected with --confirmFree
The approval record --approve-file, checked in a pipelineTeam 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 syncThe engine has what the file says.
local aheadThe file changed since the last deploy to this environment, and the engine did not.
engine aheadSomeone changed the engine, and your file has not changed since the last deploy.
differsChanged on both sides, or there is no deploy record to tell which came first.
only localThe file is not on the engine.
only on the engineThe 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:

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.