Guide / Set up a project

penstock.yaml

One file in your project says what the project is: which engine, which templates, where to deploy. Every key is explained here.

Free

What it is for

penstock.yaml is a small text file that you write by hand and commit with your diagrams. The plugin and the command line both read it. So everyone on the team, and your pipeline, gets the same engine, the same rules and the same deployment target. A change to it is reviewed like any other change.

Every key is optional. What you leave out keeps its default.

Create it

1. Open an empty diagram and answer the engine question above the canvas. The file is created for you.
2. Or create it with penstock init, which writes it with the engine guessed from your diagrams, adds penstock.local.yaml to .gitignore, and installs the penstockw wrapper.

An example

# yaml-language-server: $schema=https://raw.githubusercontent.com/kern0x1b/penstock-release/main/docs/schema/penstock.schema.json

engine: camunda-7        # classic | camunda-7 | camunda-8 | operaton | cib-seven
scriptType: groovy       # none | groovy | javascript

elementTemplates:
  - templates/connectors

linked:
  - ../order-workers

lint:
  configPath: rules/.bpmnlintrc

tests:
  language: kotlin       # java | kotlin
  out: src/test/kotlin
  package: com.example.orders.process

deployment:
  url: http://localhost:8080/engine-rest
  name: Order handling
  source: penstock

profiles:
  test:
    deployment:
      url: https://bpm-test.example.com/engine-rest
      auth:
        type: basic
        username: ${BPM_USER:ci}
  prod:
    deployment:
      url: https://bpm.example.com/engine-rest
      auth:
        type: oauth
        clientId: penstock
        tokenUrl: https://auth.example.com/oauth/token

Every key

A file that has a key Penstock does not know is marked by the schema. The schema is at schema/penstock.schema.json. Each tool carries its own copy, which is always the one that matches its version.

There are no layout settings. Auto layout uses its own spacing and .bpmnlayoutrc is not read.

Who wins when several files say different things

Four layers, in order. Each later one overrides the earlier ones.

1. penstock.yaml: the project's answer, committed. Penstock reads every folder from the project root down to the diagram and merges them, so the file nearest the diagram wins.
2. penstock.local.yaml: this machine's answer, in the same folders, read right after the file beside it. Keep it out of version control. Penstock adds it to .gitignore when it writes one.
3. profiles.<name>: the profile in force, laid over the merged result.
4. PENSTOCK_* environment variables: the last word. The name is the key path in capitals joined by underscores: PENSTOCK_DEPLOYMENT_URL, PENSTOCK_ENGINE, PENSTOCK_LINT_CONFIGPATH. true and false and whole numbers are read as such.

Also accepted: penstock.yml and penstock.json, and their .local versions.

Use an environment variable inside the file

Any text value may reference the environment: ${VAR}, or ${VAR:fallback} when it may be missing. That is how a value gets in without being written down.

auth:
  username: ${BPM_USER:ci}

Rules the editor applies for you

Camunda advises readable technical ids. Put your convention in the file and the editor applies it. Pro

conventions:
  ids:
    fromName: true
    pattern: "{Type}_{Name}"      # "Check stock" on a service task -> ServiceTask_CheckStock
  defaults:
    bpmn:ServiceTask:
      camunda:asyncBefore: true

ids rewrites the id when the name changes, and adds a number rather than colliding. defaults sets attributes on an element as it is created. Changing a task into a service task counts as creating one. Both happen inside the same editing step, so one Undo takes them back together with the change that caused them.

Commands around a stage

hooks:
  preDeploy: npm run verify-workers
  postDeploy: ./notify-release.sh
  postLayout: git add -A

A hook runs in the project root when Penstock reaches that stage. It sees PENSTOCK_FILES (one file per line), PENSTOCK_ROOT, PENSTOCK_STAGE and PENSTOCK_PROFILE. preDeploy and postDeploy also run around a deployment from an editor, and there only in a trusted project. A pre hook that exits with a non-zero code stops the stage. That is how a project says "not without this check".

Secrets

Passwords, tokens and client secrets are never read from these files and never written to them. In the editor they go to the secret store of your tool, separately for each profile, when you type them into the Connection dialog. On the command line they come from PENSTOCK_PASSWORD, PENSTOCK_CLIENT_SECRET and PENSTOCK_TOKEN. A user name or a client id is not a secret and may be in the file.

What is not in the file

Anything about how your editor looks: which toolbar actions are pinned, whether the tour has been seen, the editor theme, Sketchy drawing, the width of the sidebar and the tab you left selected, tree or flat view of the project model, the last export format. That is yours, not the project's. It lives in ~/.penstock/preferences.json, or under PENSTOCK_HOME when that is set. See Files Penstock reads and writes.

Language

The editors, the messages and the command line are in English, German, Spanish, French, Japanese, Korean, Portuguese (Brazil), Russian and simplified Chinese. The pages of this guide and the rule pages are in English.

• In an editor a locale in ~/.penstock/preferences.json comes first, if there is one. Without it the language of your tool is used, and without that the one of the browser engine the editor runs in.
• On the command line it is --lang, then the first of LC_ALL, LC_MESSAGES and LANG that is set and is not C or POSIX.
• A language Penstock does not have gives English. So does Traditional Chinese (script Hant, or the regions TW, HK and MO), and any Portuguese other than Brazil.

Only the words Penstock writes are translated. The names in your diagrams, the findings' ids and the keys of penstock.yaml stay as they are.

Completion and validation

The file starts with a yaml-language-server line that names the JSON schema. Editors that understand it, such as VS Code, give completion, validation and hover help. Tools that ship Penstock carry their own copy of the schema, so it also works with no network. See below for your tool.

A file that cannot be read is reported in a message that names the file and the error. The previous answer stays in force until the file parses again.

What to commit

What you see

• Completion and hover help while you type in penstock.yaml, in tools that read the schema.
• penstock doctor lists which files apply, the engine and the profiles.

Common problems

My setting is ignored.

A nearer file, the local file, the profile or an environment variable may override it. Run penstock doctor --format json. It prints the settings that apply after all four layers.

The editor says it cannot read my file.

The YAML is not valid. The notification names the line. Fix it. The old answer stays until then.

An editor marks a valid key as unknown.

That editor is reading the schema from the URL in the first line of the file, and the copy on this site can be older than your version of Penstock. A tool with Penstock uses its own copy. The warning does not change how Penstock reads the file.