Penstock

Guide / Set up a project

Policy pack

A policy pack keeps your team's rules, severities, conventions, palette, element templates and baselines in one folder in git, pinned by a hash, so every project and every pipeline applies the same ones. There is no server.

Free Showing the policy: free. Writing a pack: Pro. Enforcing it in a pipeline: Team in a pipeline.

What it is

The pack is a folder: .penstock/policy/, or the folder that policy: path names in penstock.yaml, or a git address and ref that is fetched only when someone runs penstock policy sync. It holds a policy.json with:

The JSON schema of policy.json is penstock-policy.schema.json.

PartPlan
Showing the active policy, in the editors and with penstock policy showFree
policy init, add-rule, pin, verify, syncPro, Team in a pipeline
Enforcing the policy in a pipeline (POLICY_PACK)Team in a pipeline

A pack is data only

Nothing in a pack runs. A file that is not json, yaml, md or txt, a symbolic link, a path outside the folder, a plugin, hook or script entry, a reserved key, or more than 200 files, 256 KB for a file or 4 MB in all is refused with the reason, and none of the pack applies.

The commands

penstock policy showWhat is active. --format json is for a pipeline.
penstock policy init --name <name>Starts a pack.
penstock policy add-rule <rule> --severity error|warn|off [--forced]Sets a rule, and whether it is forced.
penstock policy pinRecords a canonical sha256 over every file and the file list in penstock.yaml (policy.pin, comments kept) or in penstock.policy.lock.
penstock policy verifyRecomputes the pin.
penstock policy sync [--source <address>] [--allow-local-source]Fetches the pack named by policy: source into .penstock/policy-source. Nothing is fetched otherwise.

Sync accepts neither a network share nor a device path (\\host\share, //host/share, \\?\, \\.\). A local folder named by policy: source is accepted only with --allow-local-source, and an address you type with --source may be local. Git runs with a small environment, and with the file and ext transports off unless a local source was allowed.

In a pipeline

Team in a pipeline

Under CI (the CI variable, or --ci <pipeline>), penstock check fails when:

See Pipelines, reports and the bot. The pin shows that the pack was changed; it is a hash kept in your repository, not a signature.

In the editors

Every host shows the active policy in the check card and in the Problems tab, for example Policy: name v3, pinned. A finding of a policy rule carries the policy's name. The policy's severities and palette apply. The Policy screen lists the locked settings with a hint. In Penstock Web it is in the command palette.

Where the Policy screen is, by tool

JetBrains

Tools | Policy opens the Policy screen. The check card and the Problems tab show the active policy.

VS Code

The command Penstock: Policy opens the Policy screen. The check card and the Problems tab show the active policy.

Command line

penstock policy show prints the active policy. See policy.

Element templates of a pack apply in the command line and in the web editor. The plugins do not load them yet.

Common problems

None of the pack applies.
Something in it was refused: a file type, a link, a path outside the folder, a plugin or script entry, or a size limit. penstock policy show says which.
The pipeline fails on the pin.
A file of the pack changed after penstock policy pin. Pin again and commit the result.
Sync refuses a source.
It is a network share, a device path, or a local folder without --allow-local-source.