Guide / Check your work
Connections map
The configuration around a diagram that is not in the diagram, read in one place: the secrets and the MCP clients it names, and where the project defines them.
What it is
A diagram says secrets.SLACK_TOKEN and nothing in the diagram tells you whether the token exists. The connections map answers that. It reads what the diagrams name and matches it against what the project defines. Only names are shown, never values.
What is matched
- The
secrets.NAMEreferences in BPMN files and element templates, againstconnector-secretsfiles,.env, theenvironmentof Docker Compose files, Helmvalues.yaml(connectors.secretsandenv) and Spring Bootapplication.yamlor.properties. - The client id of an MCP client task, against the clients in
mcp-gateway.yamlor thecamunda.clientsettings.
The checks
Seven rules in the family connections, each with a page. They show in Check, in the Problems tab, in penstock check --only connections and in the SARIF and GitHub outputs.
| Rule | What | Needs |
|---|---|---|
connections/secret-undefined | A secret nothing defines. | Free |
connections/secret-prefix | A secret defined without the runtime prefix. | Free |
connections/mcp-client-undefined | An MCP client nobody configured. | Free |
connections/property-renamed | A Spring property renamed in Camunda 8.8, with the new name. | Free |
connections/property-removed | A Spring property Camunda 8.8 no longer reads. | Free |
connections/secret-missing-in-env | A secret defined for one environment and missing in another. | Pro |
connections/key-missing-in-env | A key defined for one environment and missing in another. | Pro |
The Connections screen
The sidebar of Penstock Web has a Connections node with a finding for every problem and an action that opens the map, and the palette of Penstock Web has a command for it.
Where the Connections screen is, by tool
JetBrains
A Connections node in the Penstock tool window, with a finding for every problem, and Connections map under Tools.
VS Code
A Connections node in the Penstock view, with a finding for every problem, and a command that opens the map.
Command line
penstock connections prints the map. See connections.
In a terminal
penstock connections
penstock connections --env prod --against dev
| Option | What it does |
|---|---|
[folder] | The project folder. It defaults to the working directory. |
--format json|text | How the answer is printed. Use json in a pipeline. |
--env <name> | Look at one environment: the shared files and the ones named for it. |
--against <name> | With --env: what the other environment defines and this one lacks, before you deploy. |
It exits 0 when nothing the runtime would fail on was found, and 1 when a diagram names something that is missing, an environment is unknown, or --against is not allowed here.
Comparing environments
Pro Team in a pipeline
penstock connections --env prod --against dev lists the secrets and keys the target lacks. The screen shows which environments lack each name. Environments come from .env.<name>, values-<name>.yaml, application-<name>.yaml and the profiles of penstock.yaml.
For an AI agent
The connections MCP tool is a read tool and is free. It reports what is referenced, where it is defined and which environment lacks it. See The MCP server.
What you see
- A map of names, with a finding for each name nothing defines.
- No secret value anywhere.
Common problems
- A secret is reported as undefined, but it exists in a cloud console.
- Secrets that live only in a console or a vault cannot be seen from the project. That is why the rule is advice and not an error.