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.
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 rules: on or off, the severity, and whether a rule is forced, so the project may not turn it off or lower it;
- conventions, and a reduced palette;
- element templates and baselines;
- the checks that must pass (check, scenarios, DMN tests, receipt);
- a name and a version.
The JSON schema of policy.json is penstock-policy.schema.json.
| Part | Plan |
|---|---|
Showing the active policy, in the editors and with penstock policy show | Free |
policy init, add-rule, pin, verify, sync | Pro, 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 show | What 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 pin | Records a canonical sha256 over every file and the file list in penstock.yaml (policy.pin, comments kept) or in penstock.policy.lock. |
penstock policy verify | Recomputes 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:
- the pin is missing or does not match;
- the project weakens a forced rule, by turning it off or lowering its severity;
- the project widens the palette;
- a required check has not run on these files, or failed.
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 showsays 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.