pubrules 0.48.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. pubrules/__init__.py +14 -0
  2. pubrules/audit.py +116 -0
  3. pubrules/audit_draft.py +295 -0
  4. pubrules/audit_prepare.py +1128 -0
  5. pubrules/cache.py +319 -0
  6. pubrules/cbor.py +45 -0
  7. pubrules/ci.py +910 -0
  8. pubrules/cli.py +1069 -0
  9. pubrules/conform.py +295 -0
  10. pubrules/doc_coverage.py +235 -0
  11. pubrules/freshness.py +75 -0
  12. pubrules/gherkin.py +348 -0
  13. pubrules/hooks.py +59 -0
  14. pubrules/hosting.py +372 -0
  15. pubrules/ignores.py +86 -0
  16. pubrules/new.py +242 -0
  17. pubrules/nightly.py +1002 -0
  18. pubrules/paths.py +32 -0
  19. pubrules/protect.py +596 -0
  20. pubrules/providers.py +129 -0
  21. pubrules/refs.py +213 -0
  22. pubrules/release-commit +1 -0
  23. pubrules/releases.py +107 -0
  24. pubrules/repos.py +67 -0
  25. pubrules/ruleset.json +43 -0
  26. pubrules/secrets_config.py +165 -0
  27. pubrules/security.py +134 -0
  28. pubrules/service_needs.py +467 -0
  29. pubrules/standard.json +635 -0
  30. pubrules/standard.py +266 -0
  31. pubrules/supply_chain.py +188 -0
  32. pubrules/tag-ruleset.json +14 -0
  33. pubrules/templates/common/AGENTS.md +32 -0
  34. pubrules/templates/common/pubrules +26 -0
  35. pubrules/templates/common/tests/features/repository.feature +11 -0
  36. pubrules/templates/common/tests/install-lock +65 -0
  37. pubrules/templates/common/tests/pytest.ini +4 -0
  38. pubrules/templates/common/tests/requirements-pubrules.txt +17 -0
  39. pubrules/templates/common/tests/requirements.txt +3 -0
  40. pubrules/templates/common/tests/steps/test_repository.py +14 -0
  41. pubrules/templates/deploy/pubdeploy +28 -0
  42. pubrules/templates/new-rust/CHANGELOG.md +3 -0
  43. pubrules/templates/new-rust/Cargo.toml +46 -0
  44. pubrules/templates/new-rust/LICENSE +202 -0
  45. pubrules/templates/new-rust/Makefile +18 -0
  46. pubrules/templates/new-rust/README.md +34 -0
  47. pubrules/templates/new-rust/SECURITY.md +26 -0
  48. pubrules/templates/new-rust/corpus/corpus.json +11 -0
  49. pubrules/templates/new-rust/deny.toml +32 -0
  50. pubrules/templates/new-rust/fuzz/Cargo.toml +23 -0
  51. pubrules/templates/new-rust/fuzz/fuzz_targets/greet.rs +8 -0
  52. pubrules/templates/new-rust/fuzz/gitignore +4 -0
  53. pubrules/templates/new-rust/fuzz/regressions/README.md +4 -0
  54. pubrules/templates/new-rust/gitignore +10 -0
  55. pubrules/templates/new-rust/src/lib.rs +91 -0
  56. pubrules/templates/new-rust/src/main.rs +19 -0
  57. pubrules/templates/new-rust/supply-chain/audits.toml +4 -0
  58. pubrules/templates/new-rust/supply-chain/config.toml +23 -0
  59. pubrules/templates/new-rust/supply-chain/imports.lock +2 -0
  60. pubrules/templates/new-rust/tests/conftest.py +9 -0
  61. pubrules/templates/new-rust/tests/features/cli.feature +14 -0
  62. pubrules/templates/new-rust/tests/steps/test_cli.py +15 -0
  63. pubrules/templates/new-rust/tests/vectors.rs +30 -0
  64. pubrules/templates/new-rust/tools/vectors/generate.py +24 -0
  65. pubrules/templates/python/Makefile +5 -0
  66. pubrules/templates/python/pubrules-python.mk +47 -0
  67. pubrules/templates/rust/Makefile +9 -0
  68. pubrules/templates/rust/pubrules.mk +138 -0
  69. pubrules/templates/rust/rust-toolchain.toml +8 -0
  70. pubrules/templates/service/pubsec +27 -0
  71. pubrules/templates/service/with-secrets +20 -0
  72. pubrules/templates/service/with-secrets.json +8 -0
  73. pubrules/variables.py +45 -0
  74. pubrules-0.48.0.dist-info/METADATA +1241 -0
  75. pubrules-0.48.0.dist-info/RECORD +79 -0
  76. pubrules-0.48.0.dist-info/WHEEL +5 -0
  77. pubrules-0.48.0.dist-info/entry_points.txt +2 -0
  78. pubrules-0.48.0.dist-info/licenses/LICENSE +202 -0
  79. pubrules-0.48.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,1241 @@
1
+ Metadata-Version: 2.4
2
+ Name: pubrules
3
+ Version: 0.48.0
4
+ Summary: The setup every package shares: managed files, reusable CI, the Rust crate standard and the Gherkin rule.
5
+ Author-email: David Schryer <schryer@gmail.com>
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Repository, https://github.com/Sustenaut/pubrules
8
+ Requires-Python: >=3.11
9
+ Description-Content-Type: text/markdown
10
+ License-File: LICENSE
11
+ Requires-Dist: PyYAML>=6
12
+ Dynamic: license-file
13
+
14
+ # pubrules
15
+
16
+ The testing and quality setup every package shares:
17
+ - the pin of pubtest, the pytest-bdd plugin and Gherkin steps every suite loads;
18
+ - the files each repository must hold, kept in step by a command;
19
+ - reusable CI workflows;
20
+ - the Rust crate standard, with a Claude Code agent that audits crates
21
+ against it.
22
+
23
+ Every package tests its behaviour the same way: Gherkin feature files, run
24
+ by pytest-bdd (or cucumber-js and quickpickle in Node), with pubtest's steps,
25
+ driving the built program as a user would. pubrules is that setup, written once.
26
+
27
+ ## The steps: pubtest
28
+
29
+ The pytest plugin and the Gherkin steps every suite loads are
30
+ [pubtest](https://github.com/Sustenaut/pubtest)'s: one grammar
31
+ ([GRAMMAR.md](https://github.com/Sustenaut/pubtest/blob/main/GRAMMAR.md)), a
32
+ pytest-bdd plugin and an npm package for cucumber-js and quickpickle. The managed
33
+ `tests/requirements-pubrules.txt` names the oldest pubtest whose steps pubrules' own
34
+ files use (`# pubtest floor: X`, which `sync --check` holds the pin to), and each repository's `tests/requirements.txt` pins the
35
+ release wheel, which its lock holds with its hash and the nightly moves to pubtest's
36
+ latest release, so a pubtest release needs no pubrules release. `pubrules sync` pins
37
+ the one the lock has where `tests/requirements.txt` pins none (`sync --check`
38
+ fails), and `pubrules lock` refuses a pubtest from an index: PyPI's `pubtest` is
39
+ another project. So every suite gets `ctx`, `binary(name)`, `run(...)`, the tag markers and the steps
40
+ (`it succeeds`, `it prints "…"`, `the result is "V"`, the files, stand-ins, HTTP and
41
+ secrets steps) without writing them. pubrules carried the plugin itself until 0.42.0;
42
+ a suite that imported `pubrules.plugin` imports `pubtest.core` instead.
43
+
44
+ ## Other packages' releases
45
+
46
+ pubrules holds no version of pubrel, pubtest, pubsec or pubdeploy. Each
47
+ repository pins them: pubrel in `ci.release.pubrel` (or the release workflow
48
+ sync wrote), pubtest in `tests/requirements.txt`, pubsec and pubdeploy in
49
+ `deploy.providers` (or the launcher sync wrote). The nightly moves each to
50
+ its latest release, as it moves any other pin. Only where a repository has
51
+ no pin yet (`pubrules new`, `pubrules init`, a launcher written for the
52
+ first time) is one read: from the release-state file `PUBRULES_RELEASES`
53
+ names, when its `releases` block lists the package, otherwise from the
54
+ package's latest GitHub release.
55
+
56
+ ```json
57
+ {"releases": {"pubrel": "0.8.0", "pubtest": "0.2.2",
58
+ "pubsec": {"version": "0.3.0", "sha256": "…"}}}
59
+ ```
60
+
61
+ A version alone, or with its wheel's sha256 (without it, the wheel is
62
+ fetched and hashed). With neither, the command stops and says so.
63
+
64
+ ## Keeping the files in step
65
+
66
+ ```sh
67
+ pubrules init --kind=rust --bin=pub # or --kind=utility, --kind=service --project=NAME, or --kind=content
68
+ pubrules lock # pin tests/requirements.txt, with hashes
69
+ pubrules sync --check # CI: fail if a managed file drifted
70
+ pubrules sync # after bumping pubrules: rewrite them
71
+ ```
72
+
73
+ A repository is one of four kinds, named in `pubrules.json`:
74
+
75
+ | Kind | What it is |
76
+ |---|---|
77
+ | `rust` | A released Rust package, held to the Rust crate standard (below) |
78
+ | `utility` | A released tool or library in any language, or several, without the Rust package's extra checks |
79
+ | `service` | A repository that deploys rather than releases, and runs its secret-needing commands through `./with-secrets` (below) |
80
+ | `content` | An authored-content repository, private: pubrules neither releases nor deploys it; its own tooling builds and checks it through the ci tests job (below) |
81
+
82
+ The kind `python` (before 0.10.0) and `python-utility` (0.10.0) are now
83
+ `utility`: a package's language doesn't decide its kind. `sync` says so
84
+ when `pubrules.json` still names an old one.
85
+
86
+ Files are **managed**, owned by pubrules and rewritten by `sync`, or
87
+ **seeded**, written once by `init` and the repository's own after that.
88
+
89
+ - **Managed:** `tests/requirements-pubrules.txt` (the shared pins and the pubrules wheel), `pubrules` (below), and `AGENTS.md`, the working rules agents and people follow in every repository, starting with when a pull request is draft (below). For a Rust package, also `pubrules.mk`, `rust-toolchain.toml`, and the crate standard with its agent (below). For a Python package (a utility whose CI is Python's), `pubrules-python.mk`: the make targets every Python package shares (`venv`, `functional`, `lock`, `sync-check`, `wheel`, `clean`, `help`), with the suite on every core (`PYTEST_ARGS ?= -n auto`) and its coverage in `coverage/coverage.xml`. Set `PYTEST_ARGS`, `FUNCTIONAL_ENV` (variables the suite needs, such as `PYTHONPATH=$(CURDIR)/src`) or `EDITABLE` (what `venv` installs editable; empty for nothing) in the Makefile, before the include. `sync --check` fails until the Makefile includes it and `pyproject.toml`'s `[tool.coverage.run]` sets `patch = ["subprocess"]` and `parallel = true`, so the coverage of xdist's workers and of the programs the suite starts is combined. For a service, `with-secrets`. A content repository has the common files only.
90
+ - **Seeded:** `tests/requirements.txt` (includes the managed one), `tests/pytest.ini`, `.github/workflows/ci.yml`, for a Rust package a `Makefile` that includes `pubrules.mk` (for a Python package, one that includes `pubrules-python.mk` and adds `check`), and for a service `with-secrets.json`.
91
+ - **Healed:** `.gitignore` is the repository's own, but it must ignore `.env`, where local tools read secrets (`./with-secrets` its Bitwarden token). `init` and `sync` append `.env` when it's missing, with a comment above it, and leave the rest of the file as it is; `sync --check` fails until it's there. A pattern that already covers it, such as `/.env` or `.env*`, counts, and a later `!.env` takes it back.
92
+
93
+ Extensions go in the seeded files, so nothing managed is ever edited by
94
+ hand. `sync --check` also fails when `tests/requirements.lock` pins another
95
+ pubrules, and in a Rust repository it runs `pubrules conform` (below).
96
+
97
+ Run as any release but the one `tests/requirements.lock` pins, pubrules
98
+ refuses the commands that judge or write the repository by its standard
99
+ (`sync`, `lock`, `supply-chain`, `doc-coverage`, `required`, `conform`,
100
+ `audit`, `record`) and says to run `make venv`, use `./pubrules`, or, when
101
+ it is the newer one, `pubrules bump`. `PUBRULES_ANY_VERSION=1` runs it anyway.
102
+ In a Rust repository, each `pubrules.mk` target that runs a tool from `.venv`
103
+ rebuilds `.venv` first when the lock has changed since `make venv` last
104
+ ran, so a moved pin never runs the old pubrules.
105
+ Its `functional` and `coverage` run the Gherkin suite on every core
106
+ (`PYTEST_ARGS ?= -n auto`, pytest-xdist, which the shared requirements
107
+ pin); `PYTEST_ARGS =` in the Makefile runs it on one. pubrules' own
108
+ `make functional` does the same.
109
+
110
+ **`./pubrules`** runs the pubrules this repository pins, whichever (if any) is
111
+ installed: `./pubrules sync --check`. It
112
+ runs `uvx` on that release's wheel, which uv fetches once and caches, in
113
+ the repository's root, from whichever directory it is called. Without uv
114
+ it says how to install it. It is managed, so `pubrules sync` moves it with
115
+ the rest when a repository moves to a new pubrules.
116
+
117
+ ## Services: `./with-secrets` and `service-ci.yml`
118
+
119
+ A service runs every command that needs a secret through `./with-secrets`,
120
+ which reads its Bitwarden project, as `with-secrets.json` says, and runs the
121
+ command with the secrets in its environment only:
122
+
123
+ ```sh
124
+ ./with-secrets terraform plan
125
+ ./with-secrets scripts/setup-backup.sh
126
+ ```
127
+
128
+ That script, managed in every repository with a `with-secrets.json`, is one
129
+ line: `./pubsec run --cwd "$PWD" -- COMMAND`. Holding a secret's value is
130
+ [pubsec](https://github.com/Sustenaut/pubsec)'s, not pubrules', so `pubrules
131
+ sync` writes `./pubsec` beside it, which runs the repository's pubsec
132
+ (`deploy.providers`' entry, or where a repository has no deploy block the one
133
+ `./pubsec` already fetches, which the nightly moves to pubsec's latest release), its wheel checked against its sha256 on every run. pubsec's README, "Services:
134
+ ./with-secrets", explains `with-secrets.json` and `pubsec run`.
135
+
136
+ `service-ci.yml` is a service's CI: `pubrules sync --check` and shellcheck,
137
+ `terraform fmt`, `init -backend=false` and `validate` when `terraform-dir`
138
+ is given, the repository's own tests when `test` is, and SonarQube Cloud's
139
+ scan (below). No job but the scan has secrets. Its `passed` job is the one check a ruleset would require; private
140
+ repositories on GitHub Free have no rulesets, so there it is a summary.
141
+
142
+ ### Sending secrets to a repository
143
+
144
+ `pubrules.json`'s `github_app` and `secrets` blocks name the values a
145
+ repository needs from Bitwarden and where each goes on GitHub, and `pubrules
146
+ sync --check` refuses one it can't use. Sending them is pubsec's:
147
+ `./with-secrets ./pubsec app-secrets [--check]` (pubsec's README, "Sending
148
+ secrets to a repository"). `pubrules app-secrets` says so, and is removed in
149
+ the next minor.
150
+
151
+ ### Creating a GitHub App
152
+
153
+ `./pubsec github-app create MANIFEST` makes an app with GitHub's manifest
154
+ flow and puts its three values in Bitwarden, where `./pubsec app-secrets`
155
+ finds them (pubsec's README, "Creating a GitHub App"). `pubrules github-app
156
+ create` says so, and is removed in the next minor.
157
+
158
+ ### Making a service account key
159
+
160
+ `./pubsec service-account-key create` makes a Google Cloud service account
161
+ key and writes it to Bitwarden from memory (pubsec's README, "Making a
162
+ service account key"). `pubrules service-account-key create` says so, and is
163
+ removed in the next minor.
164
+
165
+ ## Content repositories
166
+
167
+ A content repository holds authored information, documents or data, and is
168
+ private. pubrules neither releases nor deploys it: it has no release, no
169
+ release tags and no secrets wrapper, and any versioning of what it holds is
170
+ its own tooling's, never pubrules' or pubrel's. What that looks like depends
171
+ on the content: one body of content with no versions, or a monorepo of
172
+ content projects, each versioned on its own (as publets are, each a version
173
+ of its project). pubrules sees one repository either way, and its CI runs
174
+ whatever checks the content's tooling gives it. The line between them:
175
+ pubrules, the packages split off it and pubrel converge and version code,
176
+ configuration and state; the content's own publet packages manage the
177
+ content itself, its versioning, publication and state. `pubrules init --kind=content`
178
+ writes the common managed files only (`./pubrules`, `AGENTS.md`,
179
+ `tests/requirements-pubrules.txt`, `tests/install-lock`) and the seeded test
180
+ files, and needs no `--project`.
181
+
182
+ - **CI:** `checks` (the managed files in step, and shellcheck on the
183
+ repository's `**/*.sh` unless `with` gives `shellcheck`) and, when `with`
184
+ gives a `test`, `tests`, which runs the checks the repository's own tooling
185
+ makes, after `setup`. There is no scan: SonarQube Cloud has no code to
186
+ analyse, and does not analyse a private repository for free. A `release`
187
+ in the ci block stops sync.
188
+ - **Protect:** main's ruleset as for any repository; its protect block's
189
+ `tags` defaults to false, since there are no release tags to keep, and
190
+ `"tags": true` or a `release_app` stops sync.
191
+ - **Nightly:** governed like any other repository: the nightly moves its
192
+ pubrules, its lock, the workflows' and actions' pins and any release wheel
193
+ its requirements files pin.
194
+
195
+ ## Hosting
196
+
197
+ A repository's hosting is [pubhost](https://github.com/Sustenaut/pubhost)'s: the
198
+ Terraform modules that turn `pubrules.json`'s `hosting` block into DNS, mail,
199
+ DNSSEC, Cloud Run and bucket resources, `terraform.yml`, which applies a stack
200
+ from CI, the `deploy-static` and `docker-build` actions, and `pubhost dns check`
201
+ and `pubhost site check`. Each is used from there by commit:
202
+ `Sustenaut/pubhost/actions/docker-build@<commit> # vX.Y.Z`,
203
+ `source = "github.com/Sustenaut/pubhost//terraform/hosting?ref=<commit>" # vX.Y.Z`.
204
+ pubhost's README describes every setting of the hosting block.
205
+
206
+ pubrules keeps the block's shape: `pubrules sync` (and `sync --check`, in CI) checks
207
+ it (`src/pubrules/hosting.py`) and stops on anything it does not know, since
208
+ Terraform drops a setting its types do not name. A new provider type is learnt
209
+ here first, then by pubhost's modules. pubrules also keeps
210
+ `job-service-terraform.yml`, which checks a stack without a backend, and the
211
+ `ci / site` job ("Generated CI" below).
212
+
213
+ ## pubrules' actions
214
+
215
+ - **`actions/apt-install`:** installs the apt packages `packages` names
216
+ (separated by any whitespace, so a YAML block of lines will do;
217
+ `no-install-recommends` is `true` by default), keeping the package lists
218
+ and the .deb files in the Actions cache under
219
+ `apt-<ImageOS>-<ImageVersion>-<arch>-<sha256 of the sorted packages and
220
+ the flag>-<run id>-<attempt>` (off a hosted runner, the release's
221
+ codename and `self-hosted`), restored by all but the run, so the newest
222
+ entry wins. On a hit the packages are installed with `--no-download` and
223
+ no `apt-get update`, so nothing is fetched; a hit that will not install,
224
+ or a miss, updates the lists and installs, tried as retry tries a script,
225
+ and saves this run's entry, so a stale cache mends itself even where
226
+ `ImageVersion` never changes. GitHub evicts the older entries once no
227
+ run has used them for 7 days. A cache service that refuses,
228
+ as for a self-hosted runner whose billing is blocked, only means the
229
+ packages come from the mirror.
230
+
231
+ ```yaml
232
+ - uses: Sustenaut/pubrules/actions/apt-install@<commit> # vX.Y.Z
233
+ with: { packages: gcc-s390x-linux-gnu libc6-dev-s390x-cross qemu-user }
234
+ ```
235
+ - **`actions/cache`:** keeps what a build fetched or made between runs,
236
+ by the entries of pubrules.json's `cache` block (see "Caching a build"
237
+ below). Call it with `step: restore` before the build and `step: save`
238
+ after it, which also drops what no run used; `fresh: true` restores no
239
+ fetched entry, and `refresh: true` restores no entry at all.
240
+ - **`actions/pr-label`:** says whether the pull request a run is for
241
+ carries a label, `refresh cache` by default (`label` names another),
242
+ as its output `present`. The pull request is the event's own, the one a
243
+ merge queue group is for, or, on a push, the ones merged into the pushed
244
+ commit, which needs `pull-requests: read`. One label a person puts on a
245
+ pull request can so steer what its deploy does once it merges, such as
246
+ rebuilding everything:
247
+
248
+ ```yaml
249
+ permissions: { contents: read, pull-requests: read }
250
+ steps:
251
+ - id: refresh
252
+ uses: Sustenaut/pubrules/actions/pr-label@<commit> # vX.Y.Z
253
+ - uses: Sustenaut/pubrules/actions/cache@<commit> # vX.Y.Z
254
+ with: { step: restore, refresh: "${{ steps.refresh.outputs.present }}" }
255
+ ```
256
+ - **`actions/retry`:** runs a bash script (`run`) with `bash -ec` up to
257
+ `tries` times (3), for a step a flaky download can fail. After each
258
+ failed try but the last it warns "`<what>` failed (attempt N of T)"
259
+ (`what` is `setup` by default) and waits `pause` seconds (15); it fails
260
+ when every try did. The inputs reach the script through its
261
+ environment, so the script runs exactly as given.
262
+ - **`actions/terraform-init`:** `terraform -chdir=<dir> init <args>`
263
+ (`dir` `.`, `args` `-input=false`, `terraform` the binary), tried as
264
+ retry tries a script, then once more with every provider from
265
+ pubrules.json's `mirror.terraform`, when it names one (see "A wheel
266
+ mirror"); the lock's hashes still check what the mirror gives.
267
+
268
+ ```yaml
269
+ - uses: hashicorp/setup-terraform@<commit> # vX.Y.Z
270
+ - uses: Sustenaut/pubrules/actions/terraform-init@<commit> # vX.Y.Z
271
+ with: { dir: infra, args: -backend=false -input=false }
272
+ ```
273
+
274
+ pubrules' own reusable workflows run their setup and terraform init through
275
+ these two, pinned by a release's commit as any caller pins them: a reusable
276
+ workflow runs in the caller's checkout, where `./actions/` is the caller's.
277
+ So a change to either action reaches the workflows one release later, when
278
+ their pins move to the release that has it.
279
+
280
+ ## Deploying a service to k3s
281
+
282
+ The deploy walk is [pubdeploy](https://github.com/Sustenaut/pubdeploy)'s:
283
+ `k8s-deploy.yml`, the kustomize component `k8s/components/app`, `pubdeploy k8s
284
+ preflight` and `diagnose`, and the scheduled `deploy-check.yml`. A caller pins
285
+ `Sustenaut/pubdeploy/.github/workflows/k8s-deploy.yml@<commit> # vX.Y.Z`;
286
+ pubdeploy's README, "Deploying a service to k3s", says what it takes.
287
+ `actions/deploy-ssh` is pubdeploy's too.
288
+
289
+ ## Declaring what a service needs
290
+
291
+ pubrules.json's `deploy` block says what a service needs before it deploys,
292
+ and `./pubdeploy walk` checks and makes it (pubdeploy's README, "Declaring
293
+ what a service needs", "Making what a service needs" and "Provider
294
+ contract"). pubrules keeps three things of it:
295
+
296
+ - **`deploy.providers`** lists pubsec and pubdeploy, each the repository's
297
+ own pin, which `pubrules bump` and the nightly move through pubdeploy's
298
+ hook: `pubrules sync` adds one where none is listed (the one its launcher
299
+ already runs, or else the latest release, below), changing nothing else of
300
+ pubrules.json, and `sync --check` fails without one. pubrules holds no
301
+ version of either.
302
+ - **The launchers.** In a repository with a deploy block, `sync` writes
303
+ `./pubdeploy`, which runs the listed pubdeploy with every other
304
+ `deploy.providers` wheel, and `./pubrules` runs with every wheel, pubdeploy's
305
+ too, each fetched once into the user's cache and checked against its
306
+ sha256 on every run.
307
+ - **The hooks.** `pubrules sync` calls each `sustenaut.sync` hook,
308
+ `check(root, config, check) -> (lines, failed)`, after its own work, and
309
+ `--check` fails when one says so; `pubrules bump` calls each
310
+ `sustenaut.bump` hook, `bump(root) -> lines`, before it writes the
311
+ launchers. pubdeploy's are the deploy block's offline check and the
312
+ scheduled walk's caller, and moving deploy.providers and the uses of
313
+ pubdeploy's workflows to their latest releases. A hook that fails is said
314
+ by its name and its error's type alone. With a deploy block and no
315
+ pubdeploy installed, `sync --check` fails, saying so: CI's environment
316
+ installs it from the lock, since `tests/requirements-pubrules.txt` lists
317
+ every deploy.providers wheel, and `./pubrules` runs with each.
318
+
319
+ ## A service's needs from GitHub Actions
320
+
321
+ A step that used to be a per-repository `scripts/go-live*.sh` is a declared need
322
+ (pubdeploy's README), and the convergence engine
323
+ ([Sustenaut/convergence-engine](https://github.com/Sustenaut/convergence-engine))
324
+ checks it, or fulfils it once a person approves the plan on the engine's page. In a
325
+ repository with a deploy block, `pubrules sync` writes `.github/workflows/service-needs.yml`:
326
+ run by hand (Actions, "service-needs", Run workflow) with an `action`, `check` (the
327
+ default) or `fulfil`, and a `unit` chosen from the block's units, it calls pubrules'
328
+ reusable `service-needs.yml` at this release, which runs `pubrules service-needs` in two
329
+ steps:
330
+
331
+ 1. **ask the engine.** It asks GitHub for the run's OIDC token for the engine's address
332
+ (`id-token: write`, the one permission the caller grants; no secret), masks it, and
333
+ asks the engine, `POST /requests {"kind": "check"|"fulfil", "unit": U}`. The engine
334
+ takes a run on the default branch of a repository of an owner it lists, and walks the
335
+ unit read-only for its plan; this step follows the request until that walk ends. When a
336
+ fulfil awaits a person, it writes a box to the job summary, "Approval needed", with the
337
+ link to the request on the engine's page and the plan's needs, and an `Approval needed`
338
+ notice, then ends: the box shows on the run's page while the next step waits.
339
+ 2. **the needs of U.** It polls `GET /requests/ID` every 15 seconds, with a fresh token
340
+ each time; after a 5xx or no answer it waits 15, 30, 60, then 120 seconds before asking
341
+ again. At the end every need of the unit is shown on a line of its own: a log group
342
+ titled with an icon, the need and its state (holding what the walk found and, for a
343
+ fulfil, what it changes), an error annotation for a need missing, drifted or blocked and
344
+ a warning for one unknown, and a row of the summary's table (icon, need, type, grade,
345
+ state, found).
346
+
347
+ How the run ends:
348
+
349
+ | Action | The request ends | The run |
350
+ | --- | --- | --- |
351
+ | check | done | fails when a need is missing, drifted or blocked, naming them; otherwise succeeds |
352
+ | fulfil | done | succeeds, with each need's end state |
353
+ | fulfil | declined, expired or failed (a plan that changed since its approval, or one with nothing the engine can fulfil, among them) | fails, with the engine's reason |
354
+ | fulfil | still awaiting, or still running, when `timeout-minutes` (300) is up | succeeds, saying so: the engine runs it once approved |
355
+
356
+ A check asks no one and changes nothing. Nothing the run prints holds an email or other
357
+ value: the engine names no approver to a caller, the needs come by name, state and what
358
+ was found, and any email-shaped text is taken out. `sync` also lists the caller under
359
+ `github.actions-oidc` in integrations.json, removes the `go-live.yml` pubrules 0.43.2
360
+ wrote, and `sync --check` fails when the caller differs or is left behind without a deploy
361
+ block. pubrules.json's `service-needs` block, all optional, reaches the caller:
362
+
363
+ ```json
364
+ "service-needs": {"engine": "https://convergence.sustenaut.eu", "timeout-minutes": 300, "claude-dispatch": false}
365
+ ```
366
+
367
+ `engine` is the engine's address (and the token's audience), `timeout-minutes` how long a
368
+ run waits, and `claude-dispatch` whether Claude may start the workflow too. The engine does
369
+ not enforce `claude-dispatch` yet: a run's OIDC token names who started it (`actor`), and a
370
+ dispatch by Claude through a person's token reads as that person, so telling them apart
371
+ needs its own mark first. ci.runs-on's default label is the job's runner. The scheduled
372
+ `deploy-check.yml` (pubdeploy's) stays until a check from here serves in its place.
373
+
374
+ ## Terraform from CI
375
+
376
+ `terraform.yml`, the reusable workflow that applies a stack from the default
377
+ branch, is [pubhost](https://github.com/Sustenaut/pubhost)'s
378
+ (`Sustenaut/pubhost/.github/workflows/terraform.yml@<commit> # vX.Y.Z`).
379
+
380
+ ## Caching a build
381
+
382
+ A build that downloads slow-changing data, or makes many outputs one by
383
+ one, can keep both between runs by entries the repository states in
384
+ pubrules.json. The cache block is one map of named entries, each with the
385
+ same keys:
386
+
387
+ ```json
388
+ "cache": {
389
+ "data": { "path": "data", "refresh": "week" },
390
+ "packs": { "path": ".packcache", "unit": "data/areas/{unit}/",
391
+ "inputs": ["data/boundaries.geojsonl", "mapbuild/*.py"],
392
+ "tools": ["tippecanoe --version"] },
393
+ "overview": { "path": ".packcache/overview",
394
+ "inputs": ["data/national/", "data/boundaries.geojsonl", "mapbuild/*.py"],
395
+ "tools": ["tippecanoe --version"] }
396
+ }
397
+ ```
398
+
399
+ | Key | What |
400
+ |---|---|
401
+ | `path` | the file or directory kept between runs |
402
+ | `refresh` | `run`, `day`, `week` (ISO week), `month` or `never` |
403
+ | `version` | a free string; changing it fetches anew |
404
+ | `inputs` | files, directories or globs the key depends on |
405
+ | `tools` | commands whose output counts, such as `tippecanoe --version` |
406
+ | `unit` | one pattern with `{unit}`, filled from `--unit`, so each unit gets its own fingerprint |
407
+
408
+ An entry needs `refresh` or `inputs` (or both). An unknown key fails
409
+ `pubrules sync`, naming it. Each entry gets its own cache key, and a block
410
+ holds at most eight entries.
411
+
412
+ - A **fetched** entry (`refresh` other than `run`, and no `inputs` or
413
+ `unit`) is kept for its period: the first run of a period fetches it,
414
+ and later runs restore it. A fresh run restores none.
415
+ - A **made** entry (`inputs`, `unit` or `refresh: run`) is restored from
416
+ the latest run. The build makes it through
417
+
418
+ ```sh
419
+ pubrules cache run packs --unit north/alpha --output pack.pmtiles -- bin/build-pack ...
420
+ ```
421
+
422
+ which fingerprints the unit (the entry's name, the unit, the `unit`
423
+ pattern filled in, each `inputs` entry, each `tools` command's output,
424
+ and the version), copies the outputs when that fingerprint was made
425
+ before, and otherwise runs the command and keeps what it wrote. It
426
+ prints `reused packs north/alpha` or `built packs north/alpha`; the
427
+ command's own output goes to stderr.
428
+
429
+ In a workflow, `actions/cache` restores before the build and saves after
430
+ it. Saving first drops what no run used, so a made entry keeps one
431
+ build's worth (`pubrules cache prune` does the same by hand). With
432
+ `refresh: true` (`pubrules cache plan --refresh`) the restore step restores
433
+ nothing, so the build fetches and makes everything anew; `actions/pr-label`
434
+ sets it from a `refresh cache` label on the pull request.
435
+
436
+ ```yaml
437
+ - uses: Sustenaut/pubrules/actions/cache@vX.Y.Z
438
+ with: { step: restore, fresh: "${{ inputs.fresh || false }}" }
439
+ - run: bin/build
440
+ - uses: Sustenaut/pubrules/actions/cache@vX.Y.Z
441
+ with: { step: save }
442
+ ```
443
+
444
+ ## Checking a public site
445
+
446
+ `pubhost site check` and its WEB- rules are
447
+ [pubhost](https://github.com/Sustenaut/pubhost)'s, and its `deploy-static` runs
448
+ it before every deploy. Their exceptions are declared in `pubrules.json`'s
449
+ `exceptions`, beside the Rust standard's, which `pubrules conform` reads alone.
450
+
451
+ ## The supply-chain report
452
+
453
+ `pubrules supply-chain CRATE...` writes each crate's `SUPPLY-CHAIN.md` beside
454
+ its manifest, from the repository's `cargo vet` files (`supply-chain/`).
455
+ The report lists every crate it builds, for any target, and marks build
456
+ scripts and procedural macros. It says how each is vouched for: an imported
457
+ audit, a trusted publisher, or an exemption with its evidence. `pubrules.mk`
458
+ runs it as `make supply-chain`, and `make supply-chain-check` fails when a
459
+ committed report is stale. Set `SUPPLY_CHAIN_CRATES` in the Makefile to the
460
+ crates that are published.
461
+
462
+ ## The checks the standard requires
463
+
464
+ Every `[checked]` rule in the Rust crate standard has a stable ID and names
465
+ what checks it: `[checked: RS-DOC-04, make doc-coverage-check, library]`.
466
+ `make standard` generates `standard.json` from those tags, and it ships in
467
+ pubrules. `pubrules required` reads it, and the repository's crates, and prints
468
+ the make targets each `rust-ci.yml` job must run:
469
+
470
+ ```sh
471
+ $ pubrules required
472
+ gates=fmt-check lint doc doc-coverage-check publish-check
473
+ functional=functional vectors-check supply-chain-check
474
+ msrv=msrv
475
+ fuzz=fuzz-smoke
476
+ audit=deny vet
477
+ cross_job=true
478
+ ...
479
+ ```
480
+
481
+ A command-line tool, with no library target, is not held to the library
482
+ rules (`doc-coverage-check`). `pubrules.mk` provides every target the
483
+ standard names. A repository sets the variables they read in its Makefile:
484
+
485
+ | Variable | Default | Read by |
486
+ |---|---|---|
487
+ | `PUBLISHED_CRATES` | `SUPPLY_CHAIN_CRATES` | `doc-coverage`, `publish-check`, `msrv` |
488
+ | `VECTORS_GENERATE` | `./tools/vectors/generate.py` | `vectors`, `vectors-check` |
489
+ | `VECTORS_DIRS` | `testdata` and `crates/*/testdata`, where present | `vectors-check` |
490
+ | `FUZZ_TARGETS` | every `fuzz/fuzz_targets/*.rs` | `fuzz-smoke` |
491
+ | `MSRV` | the first `rust-version` in `Cargo.toml` | `msrv` |
492
+
493
+ `pubrules doc-coverage [--check] [CRATE...]` writes each published library's
494
+ `TESTING.md`: every public item, the examples its docs run, and the tests
495
+ whose `// covers:` comment names it. With `--check`, it fails on a public
496
+ function with no example, a `// covers:` naming no public item, or a stale
497
+ `TESTING.md`. It lives here so every repository runs
498
+ the same version.
499
+
500
+ ## Conformance, and declared exceptions
501
+
502
+ `pubrules conform` checks what no make target can, and `pubrules sync --check`
503
+ runs it in every Rust repository:
504
+
505
+ | Rule | Checked |
506
+ |---|---|
507
+ | RS-DOC-01 | each published library declares `pub mod _documentation` |
508
+ | RS-DOC-03 | each published library sets `missing_docs` in its lints |
509
+ | RS-SAFE-01 | each published crate sets `unsafe_code = "forbid"` |
510
+ | RS-TEST-01 | `testdata/` (or `crates/*/testdata/`) exists |
511
+ | RS-FUZZ-01 | `fuzz/fuzz_targets/*.rs` exists |
512
+ | RS-SUP-01 | `deny.toml` keeps the shared baseline, and `supply-chain/config.toml` imports the shared audit sets |
513
+ | RS-SUP-04 | `SECURITY.md` exists |
514
+ | RS-SUP-05 | the release key `release.json` names is labelled for what it releases ("example-crate release key"), not with a person's name: its label is public in every release it signs |
515
+ | RS-REL-01 | `release.json` declares `pubrules audit --check` as a security check |
516
+
517
+ It also checks that every workflow calling `rust-ci.yml` pins the pubrules
518
+ version the lock pins, so a repository's CI cannot fall behind the standard
519
+ its lock names. The published crates are those that do not set
520
+ `publish = false`, or the list `"published"` in `pubrules.json` gives.
521
+
522
+ A repository that cannot meet a rule yet declares an exception in
523
+ `pubrules.json`:
524
+
525
+ ```json
526
+ { "kind": "rust",
527
+ "exceptions": [
528
+ { "rule": "RS-TEST-01", "reason": "no independent source for the version arithmetic yet", "until": "2027-01-01" } ] }
529
+ ```
530
+
531
+ An excepted rule's conformance checks are skipped, its make targets leave
532
+ `pubrules required`'s plan, and `pubrules conform` lists it as open. An
533
+ exception past its `until` date, or naming no rule, fails.
534
+
535
+ ## Every test is a Gherkin scenario
536
+
537
+ `pubrules sync --check` holds every repository but a content one to the
538
+ rule this README opens with, and `pubrules gherkin` runs that check alone:
539
+
540
+ | Rule | Checked |
541
+ |---|---|
542
+ | TEST-01 | there is a `.feature` file with a scenario, and no feature file without one |
543
+ | TEST-02 | no test runs outside a scenario: a test module's `test*` functions are pytest-bdd bindings (`scenarios(...)`, or an empty function decorated with `@scenario`); there is no `Test*` class, no `unittest.TestCase`, no Node test file (`*.test.js`, `*.spec.ts`, or a script in a `test/` directory that loads a test runner such as `node:test` or `vitest`) and no test shell script (`test-*.sh`, `*-test.sh`, `*.test.sh`) |
544
+ | TEST-03 | every feature file runs: a `scenarios()` or `@scenario` call names it or its directory, resolved as pytest-bdd resolves it (`bdd_features_base_dir` in the nearest `pytest.ini`, or the module's own directory), unless the repository runs a Node Gherkin runner (`@cucumber/cucumber`, `quickpickle` or `@amiceli/vitest-cucumber` in its own or a package's package.json, or a `cucumber.*` config), which runs every feature it is given |
545
+ | TEST-04 | every scenario has a `When` among its own steps, the one action it tests (an `And` or `But` takes the keyword before it); a `When` in a `Background`, or in a docstring, does not count |
546
+
547
+ A scenario sets something up (`Given`), takes one action (`When`) and checks
548
+ what came of it (`Then`), on the steps of pubtest's GRAMMAR.md: a suite
549
+ writes its own Givens and its own When, through `attempt`, and takes every
550
+ check from pubtest. A scenario of one `Then` that tests a function in one go
551
+ was the first step onto Gherkin, and TEST-04 retires it. TEST-04 came after
552
+ the repositories had suites, so the move from a pubrules before the release
553
+ that brings it (0.43.3), or from any pubkit (its name before 0.43.0),
554
+ (`pubrules bump`, or the nightly's pins) writes its exception, until 2026-12-31, into a
555
+ repository that fails it, with the count of scenarios that have no When;
556
+ one that passes gets none, and no later move adds one.
557
+
558
+ Fixtures, steps, fakes and setup files are not tests: a Node file that loads a Gherkin runner holds steps or their
559
+ support, even beside node:test's `mock`. A Rust crate's `#[test]`s and doc tests are the Rust crate
560
+ standard's (RS-DOC-02, RS-TEST-02), and stay. `pubrules init` seeds
561
+ `tests/features/repository.feature` and its steps, so a new repository
562
+ starts in step.
563
+
564
+ A repository that cannot meet a rule yet declares an exception, read as
565
+ the Rust crate standard's are:
566
+
567
+ ```json
568
+ { "exceptions": [
569
+ { "rule": "TEST-02", "reason": "the worker's node:test tests move to cucumber-js", "until": "2027-01-31" } ] }
570
+ ```
571
+
572
+ `sync --check` lists each open exception, and fails on one past its date.
573
+
574
+ ## A release cites a current audit
575
+
576
+ The judged rules need a reader, so a release needs a report by the
577
+ rust-crate-quality agent (RS-REL-01). For a release, the agent writes it to
578
+ `audit/<package>-<version>.md`, with a header:
579
+
580
+ ```
581
+ ---
582
+ package: example-crate
583
+ version: 0.1.1
584
+ standard: <pubrules audit --standard>
585
+ blocking: 0
586
+ date: 2026-10-13
587
+ auditor: rust-crate-quality
588
+ ---
589
+ ```
590
+
591
+ `pubrules audit --check [PACKAGE VERSION]` passes only on a report for that
592
+ release, made against the standard this pubrules ships, with no finding that
593
+ blocks a release and no rule left unjudged. Without arguments it reads the release `pubrel prepare` is
594
+ cutting from `PUBREL_PACKAGE` and `PUBREL_VERSION`. A repository declares it
595
+ in `release.json`:
596
+
597
+ ```json
598
+ { "name": "quality audit current", "run": ".venv/bin/pubrules audit --check",
599
+ "version": ".venv/bin/pubrules --version" }
600
+ ```
601
+
602
+ `pubrel prepare` runs every declared check before it changes anything, so it
603
+ cuts no release without a current audit. It records each check's last line
604
+ in the release's signed security record, so the release cites its report.
605
+ Changing the standard makes earlier reports stale: a release after that
606
+ needs a new audit.
607
+
608
+ ### Preparing the report
609
+
610
+ ```sh
611
+ ./pubrules audit prepare --package example-crate # audit/example-crate-<next>.md
612
+ with-secrets ./pubrules audit draft --package example-crate # optional: Claude drafts the judged rules
613
+ ```
614
+
615
+ `pubrules audit prepare --package NAME` writes the report for the release
616
+ `pubrel next --package NAME` gives (or `--version`). It decides every rule a
617
+ machine can decide, and leaves the rest for a person:
618
+
619
+ - **The header**, as above, adds `commit` (the commit audited) and
620
+ `last-release` (the package's last release tag).
621
+ - **Each finding** goes under its severity, with its rule, file and line.
622
+ Builds and lints:
623
+ - `cargo doc` and `cargo clippy` warnings for the package, and its
624
+ doctests;
625
+ - a library's docs built from the packaged crate on nightly, as docs.rs
626
+ builds them;
627
+ - `cargo publish --dry-run`, and the build on the package's
628
+ `rust-version`;
629
+ - the make targets the standard names: `doc-coverage-check`,
630
+ `supply-chain-check`, `vectors-check`, `deny` and `vet`.
631
+
632
+ The docs and the manifest:
633
+ - public functions with no example, or returning a `Result` with no
634
+ `# Errors`;
635
+ - examples that unwrap, or use `?` without the hidden `Ok`;
636
+ - public error enums that are not `#[non_exhaustive]`;
637
+ - crate-root sections that are missing or out of order, and
638
+ features, MSRV and versioning against `Cargo.toml` and `release.json`;
639
+ - each "Related crates" row's version against `Cargo.lock`;
640
+ - the README's sections, the `Cargo.toml` metadata, and unanchored
641
+ `include` patterns;
642
+ - each tool `SECURITY.md` names, against the workflows that run it and
643
+ when, and its imported audit sets against `supply-chain/config.toml`;
644
+ - for a command-line tool, `--help` run: does it exit 0 to stdout?
645
+ - **Each rule that needs judgement** is under "Needs review", marked
646
+ `[needs review]`, with what the machine found for it. Examples: the
647
+ hidden setup lines, the functions that can panic, `usize` in
648
+ signatures, the Related crates rows, the test vectors' sources, the
649
+ entry points beside the fuzz targets, and the sentences section 10
650
+ rules out.
651
+
652
+ The judged rules have no IDs in the standard. `standard.json` keys them by
653
+ section and place (`1.6` is Related crates), which holds while the
654
+ standard's text does, and a report names that text's sha256. `--check`
655
+ fails while any `[needs review]` mark remains. A person judges each rule,
656
+ moves what they find into the sections above, counts `blocking` again, and
657
+ removes the mark. `--quick` skips what takes minutes (the docs.rs, MSRV and
658
+ publish builds, and the make targets). An existing report is written over
659
+ only with `--force`, since it may hold a review.
660
+
661
+ `pubrules audit draft --package NAME` asks Claude to draft those rules. It
662
+ sends the Messages API:
663
+
664
+ - the package's diff since its last release tag, without lockfiles and
665
+ generated files;
666
+ - the rules still marked, each with what the machine found;
667
+ - the last release's report, when there is one.
668
+
669
+ It asks for JSON matching a schema: per rule a verdict, findings with file
670
+ and line, and the reasoning. It merges each draft into the report, marked
671
+ `[machine-drafted by MODEL: needs human review]`, and adds the drafted
672
+ findings that block to `blocking`. `--check` refuses that mark too, so a
673
+ person still reads every draft. The key is `ANTHROPIC_API_KEY`: run it
674
+ through a `with-secrets` whose Bitwarden project holds a secret of that
675
+ name, or export it. The model is `--model`, `PUBRULES_AUDIT_MODEL`, or
676
+ `claude-opus-5-5`. `ANTHROPIC_BASE_URL` points it elsewhere, as the tests
677
+ do. A refusal, an error or an answer cut short writes nothing.
678
+
679
+ ## The Rust crate standard, and an agent that audits against it
680
+
681
+ [**The Rust crate standard**](plugins/rust-crate-quality/rust-crate-standard.md)
682
+ is what a crate published from these repositories is held to, whether a
683
+ library or a command-line tool. It covers:
684
+ - crate and item docs in the style of BurntSushi's crates;
685
+ - test vectors and `// covers:` links;
686
+ - fuzzing and packaging;
687
+ - Cargo's version convention, with API checks;
688
+ - the supply-chain record;
689
+ - cross-platform CI;
690
+ - plain writing.
691
+
692
+ Each rule is marked *checked* (a tool enforces it) or *judged* (it needs
693
+ reading). The standard ends with what was deliberately not adopted.
694
+
695
+ The **`rust-crate-quality` agent** audits a crate against that standard, and
696
+ writes or fixes its docs to meet it. pubrules' repository is a Claude Code
697
+ plugin marketplace, so the agent installs once for every repository, and
698
+ none of them needs a `.claude/` folder. In Claude Code:
699
+
700
+ ```
701
+ /plugin marketplace add Sustenaut/pubrules
702
+ /plugin install rust-crate-quality@pubrules
703
+ ```
704
+
705
+ Then ask for it by name, in any repository:
706
+
707
+ - "Use rust-crate-quality to audit example-crate." It returns a report and
708
+ edits nothing.
709
+ - "Use rust-crate-quality to fix the docs of pubrel." It edits
710
+ documentation, then re-runs the checks.
711
+
712
+ Claude Code also offers it unprompted when you ask whether a crate is ready
713
+ to publish.
714
+
715
+ What it does:
716
+
717
+ 1. Reads the standard. It ships with the agent, so the agent never works
718
+ from memory.
719
+ 2. Runs the checks the repository has (`make doc`, `lint`, `msrv`,
720
+ `publish-check`, `doc-coverage-check` and the like) and reports what they
721
+ say. It doesn't judge those rules again.
722
+ 3. Builds the docs as docs.rs will: from the packaged crate, on nightly,
723
+ with no warnings.
724
+ 4. Reads the docs and code for the judged rules. It verifies claims, such
725
+ as each "Related crates" row, rather than trusting them.
726
+ 5. Reports each finding with its rule, file and line, from what blocks a
727
+ release down to what is worth considering.
728
+
729
+ **What it changes:** documentation only. That means doc comments, the
730
+ README and `SECURITY.md`. Anything that needs a code change, such as
731
+ `#[non_exhaustive]` or a `u64` for a peer-supplied size, comes back as a
732
+ finding for you to decide.
733
+
734
+ **What it never does:** edit generated files, which it regenerates instead,
735
+ or record the change. Commit its edits as usual, with `pubrel add internal
736
+ "..."`.
737
+
738
+ `/plugin marketplace update pubrules` picks up a newer standard.
739
+
740
+ ## Starting a package
741
+
742
+ pubrules new --name=pubfoo --tag=PKG-PUBFOO-10-2026 [--description=TEXT]
743
+
744
+ In an empty repository, writes a crate that passes every check from its
745
+ first commit: the managed and seeded files, docs, test vectors, a fuzz
746
+ target, Gherkin scenarios, `deny.toml`, `supply-chain/`, `SECURITY.md`,
747
+ `release.json` with its security checks (the quality audit among them), and
748
+ a release key labelled "pubfoo release key", its secret in the gitignored
749
+ `corpus/.publet`. It pins pubrel (`ci.release.pubrel`) and pubtest
750
+ (`tests/requirements.txt`) at the releases the release state lists, or
751
+ else at their latest GitHub releases ("Other packages' releases", above).
752
+ Its repository is `--owner`'s, by default the owner the
753
+ `origin` remote names; without either it stops. It refuses a `pubrel` older
754
+ than 0.5.3 or a `pub` older than 0.2.1, and prints the steps it does not take
755
+ itself: the protect block to add to `pubrules.json`, and switching the repository
756
+ on in the release app.
757
+
758
+ ## Backing up signing keys
759
+
760
+ A repository names every signing key it uses, and where it is backed up, in
761
+ `pubrules.json`:
762
+
763
+ ```json
764
+ "signing_keys": [
765
+ {"path": "corpus/.publet/signing.key",
766
+ "bitwarden": {"project": {"id": "PROJECT-UUID", "name": "Pub"},
767
+ "name": "pub-signing-key-example"}}
768
+ ]
769
+ ```
770
+
771
+ The project is found by its `id`; `name` is a label for people, and a run
772
+ warns when Bitwarden's name for the project has changed. A plain string is
773
+ taken as an id when it is a UUID, else as a name, in any case.
774
+
775
+ `path` is from the repository's root, or from the home directory when it
776
+ starts with `~/`: a key kept outside any repository, such as one under
777
+ `~/.config`, is declared by the repository whose tools use it. `pubrules sync
778
+ --check` refuses a block it can't use.
779
+
780
+ Backing them up is pubsec's: `./pubsec signing-key backup [--under DIR]
781
+ [--dry-run]` writes each declared key on this machine that its project lacks,
782
+ from memory, never overwriting one (pubsec's README, "Backing up signing
783
+ keys"). `pubrules signing-key backup` says so, and is removed in the next minor.
784
+
785
+ ## Protecting main and the release tags
786
+
787
+ Every repository's default branch carries the same ruleset,
788
+ [`src/pubrules/ruleset.json`](src/pubrules/ruleset.json), which ships in the
789
+ wheel: it cannot be deleted or force-pushed, it changes only by pull
790
+ request (no approval needed), merged by GitHub's merge queue, and nobody
791
+ may bypass it. "Merge when ready" puts a pull request in the queue, which
792
+ merges it into main as it stands then, together with the pull requests
793
+ ahead of it, runs the required checks on that merge (the `merge_group`
794
+ event, which the CI `pubrules sync` writes runs on), and merges only when
795
+ they pass. So the tree the checks passed is the tree main holds after the
796
+ merge, the run on main repeats the queue's, and tagging a release needs no
797
+ tests of its own, yet nobody has to bring a branch up to date by hand:
798
+ pull requests stacked behind one another merge one at a time. GitHub
799
+ offers a merge queue only to an organization's public repositories (and to
800
+ private ones on Enterprise Cloud); a repository without one, `"queue":
801
+ false` in its entry or `--no-queue`, instead merges only after the checks
802
+ pass on a branch that is up to date with main. `pubrules protect` works this
803
+ out itself: it reads each repository's owner and visibility (and a private
804
+ one's organization plan) and leaves the queue out, with a note, for a
805
+ personal account's repository or a private one off Enterprise Cloud, and
806
+ should GitHub still refuse the `merge_queue` rule, it warns and tries once
807
+ more without it. The generated `pr.yml`'s `merge_group` trigger then never
808
+ fires, and does no harm. Which repositories carry it, and the checks each
809
+ requires, is local configuration, not part of pubrules:
810
+
811
+ pubrules protect [--check] [--no-tags] [--no-queue] [--repos FILE | --require CHECK...] [REPO...]
812
+
813
+ creates the ruleset in each repository, or updates the ruleset already on
814
+ the default branch to match, renaming it. It does the same for the release
815
+ tags' ruleset, [`src/pubrules/tag-ruleset.json`](src/pubrules/tag-ruleset.json):
816
+ nobody may create, move or delete a `v*` tag, and only GitHub Actions may
817
+ bypass it. GitHub refuses the GitHub Actions app as a bypass actor in an
818
+ organization's repository, so such a repository names its release GitHub App
819
+ with `"release_app": ID` in its entry, and its tags let that app through
820
+ instead (without it, a repository of the one owner pubrules still knows gets that
821
+ owner's app, with a warning): installed on the organization, with contents
822
+ write only, and its id and private key as the organization secrets
823
+ `RELEASE_APP_ID` and `RELEASE_APP_KEY`, which the CI `pubrules sync` writes
824
+ passes to pubrel's release workflow (pubrel 0.6.1 and later), where `pubrel
825
+ tag` uses the app's token. So the one way to release is the signed one:
826
+ `pubrel prepare` on your machine, then merging the release pull request,
827
+ after which CI runs `pubrel tag` on main. Put the tag ruleset on a
828
+ repository only once its CI passes the two secrets, or `pubrel tag` is
829
+ refused there. A tag pushed by hand is refused. A repository
830
+ that releases no tags, such as a site, goes without the tag ruleset:
831
+ `"tags": false` in its entry, or `--no-tags`. It calls the GitHub API through
832
+ `gh`, signed in as the repositories' owner, since only an admin may change
833
+ a ruleset. `--check` changes nothing: it prints how each repository
834
+ differs, a setting GitHub adds with its own default aside, and fails when
835
+ one does. When GitHub rejects a ruleset, it prints GitHub's reasons.
836
+
837
+ The repositories come from one of:
838
+
839
+ - a repos file, with `--repos FILE` ([The repos file](#the-repos-file)): the
840
+ repositories it marks to protect, each with the checks its own `pubrules.json`
841
+ says;
842
+ - `--require CHECK`, repeated, and the `REPO` arguments, with no file:
843
+ `pubrules protect --require "ci / passed" example-org/newrepo`.
844
+ - the repository's own `pubrules.json`, which says how it is protected:
845
+ `"protect": {"checks": ["ci / passed"], "tags": false, "queue": false, "release_app": 12345}`
846
+ (`tags` and `queue` default to true). A `REPO` is read from the `pubrules.json`
847
+ on its default branch, and `pubrules protect` with no list and no `REPO`,
848
+ run inside a repository, reads `./pubrules.json` for the repository
849
+ `origin` points at. The block takes only `checks`, distinct non-empty
850
+ names, `tags`, `queue` and `auto_merge`, true or false, and `release_app`, a positive integer;
851
+ anything else, or a pubrules.json that is not JSON, is refused before GitHub is asked, and `pubrules
852
+ sync --check` refuses it too.
853
+
854
+ `pubrules sync` also holds `checks` to what the repository's workflows report
855
+ where the ruleset waits for them: on the merge queue's commit (`merge_group`),
856
+ or, with `"queue": false`, on the pull request's. A required check nothing
857
+ reports there is never passed, so the queue waits for it forever, and sync
858
+ fails, naming it. A check counts as reported when a job of a workflow that runs
859
+ on that event has it as its name (or id), or, for a check `PREFIX / job`, when
860
+ such a job named `PREFIX` calls a reusable workflow (whose own job names sync
861
+ does not read). `SonarCloud Code Analysis`, which SonarQube Cloud's app posts,
862
+ counts only when such a workflow scans on every run: no workflow sync writes
863
+ scans in the merge queue, which SonarQube Cloud refuses, so a repository with
864
+ a merge queue drops it from `checks`. `ci / sonar`
865
+ still fails `ci / passed` on the quality gate, on the pull request.
866
+
867
+ It also turns on secret scanning and push protection on each public repository, unless
868
+ its block says `"secret_scanning": false`. It never turns them off, and leaves a private
869
+ repository alone, since they need GitHub Advanced Security there. Reading them needs
870
+ Administration read, and a token without it changes nothing and fails nothing.
871
+ Each public repository's dependency graph and Dependabot alerts are turned on too:
872
+ the review job's dependency review fails without them, and GitHub leaves them off on a
873
+ new repository. `protect --check` reports them off.
874
+
875
+ `auto_merge` is the repository's "Allow auto-merge" setting, which lets a
876
+ pull request be set to merge by itself once the ruleset's required checks
877
+ pass (`gh pr merge --auto`). It loosens nothing: the ruleset still decides
878
+ what may merge, and without the merge queue the branch must still be up to
879
+ date with main. `true` turns it on, `false` off, and without it protect
880
+ leaves the setting as it is; `--check` reports a setting that differs.
881
+
882
+ Here, `make protect` (or `make protect-check`, or `make protect
883
+ REPOS=example-org/example-site`) runs it, making the venv first if there is none.
884
+
885
+ ### Pull requests: ready, or draft
886
+
887
+ A pull request opens **ready for review** by default: the required checks
888
+ above gate the merge, and `ci / passed` fails when any CI job does,
889
+ SonarQube Cloud's quality gate included (below), so draft adds no safety.
890
+ It is **draft** only when something else must happen first -- another
891
+ pull request merged, a release published, a pin moved, someone's decision
892
+ -- and its description says what it waits on. The managed `AGENTS.md`
893
+ carries this rule into every repository, where coding agents read it.
894
+
895
+ ### Branches: up to date with main
896
+
897
+ Before each push, a branch takes in `origin/main`: rebased onto it if it
898
+ was never pushed, `origin/main` merged into it if it was pushed or has a
899
+ pull request, so no force push moves a reviewer's view. A conflict is
900
+ resolved only when the resolution is clear; otherwise the push waits and
901
+ says what conflicts. A folder that only follows main fast-forwards. It
902
+ runs when the branch gets new code, never on a timer, so a pull request
903
+ arrives as up to date as the ruleset requires. The managed `AGENTS.md`
904
+ carries this rule too.
905
+
906
+ ## The release board
907
+
908
+ The board that grades every repository A to E, and the commands a control
909
+ plane runs across many repositories (state files, their GitHub variables,
910
+ freshness, and the nightly's loop), are
911
+ [pubfleet](https://github.com/Sustenaut/pubfleet)'s. It grades protection
912
+ against this pubrules' rulesets, as `pubrules protect --check` does.
913
+
914
+ ## The repos file
915
+
916
+ Which repositories `pubrules protect` acts on can come from outside it, in one file:
917
+
918
+ ```json
919
+ { "repositories": [
920
+ { "repo": "example-org/some-tool", "protect": true, "govern": true, "project": "tools" },
921
+ { "repo": "example-org/some-site", "protect": true, "govern": false }
922
+ ] }
923
+ ```
924
+
925
+ `protect` says it should carry pubrules' rulesets, and `govern` that a nightly
926
+ keeps it current; each is false when left out. `project`, optional, labels it on
927
+ the board. How a repository is protected stays in its own `pubrules.json`'s
928
+ protect block. `pubrules protect [--check] --repos FILE` reads it; pubfleet reads
929
+ the same file, and makes it from an owner's state file.
930
+
931
+ A repository's `pubrules.json` may name the GitHub variables it reads, never their
932
+ values, and the workflow that takes them in:
933
+
934
+ ```json
935
+ "variables": { "names": ["SOME_SETTING", "SOME_MAP"], "deploy": "deploy.yml" }
936
+ ```
937
+
938
+ `pubrules sync --check` refuses a block of the wrong shape. The values are in the
939
+ owner's state file, which pubfleet keeps GitHub to.
940
+
941
+ ## The nightly
942
+
943
+ `pubrules nightly --pubrel V --body FILE`, run in one repository's checkout,
944
+ moves it and its dependencies on to this pubrules, in up to five commits on the
945
+ current branch, and writes the pull request's body. pubfleet's `nightly.yml`
946
+ runs it in each repository a control plane governs, and keeps one pull
947
+ request per repository on its `pubrules-nightly` branch. The commits:
948
+
949
+ 1. every outdated pub* pin (`pubrules pins`): the latest pubrules in any of its
950
+ `*-ci.yml` workflows, pubrel's release workflow and `pubrel-version`,
951
+ each tool `ci.tools` pins by tag, to the latest release of
952
+ its git repository, every other repository's reusable workflow or
953
+ action a hand-written workflow pins at a release
954
+ (`OWNER/REPO/.github/workflows/...@`, `OWNER/REPO/actions/...@`) and
955
+ every other repository's Terraform module a `.tf` file sources at a
956
+ release (`source = "github.com/OWNER/REPO//PATH?ref=..."`), to that
957
+ repository's latest release, except a `deploy.providers` package's,
958
+ which its own bump hook moves, and the crates `nightly.pins.crates`
959
+ names in `Cargo.lock`. A pin moves to the commit of the new release's
960
+ tag, with its version in a comment (for a module source, after the
961
+ closing quote: `?ref=<commit>" # vX.Y.Z`), and one still pinned by tag
962
+ moves to its commit. A pin of a pubrules action, workflow or module this
963
+ pubrules does not ship stays where it is, and `sync --check` fails on it
964
+ until it is taken from the repository it moved to;
965
+ 2. every third-party GitHub Action (`pubrules actions`) a hand-written
966
+ workflow or one of the repository's own composite actions (`action.yml`,
967
+ outside `node_modules` and `target`) pins by commit with its version in
968
+ a comment, as `uses: actions/checkout@<commit> # v5.1.0`, moved forward
969
+ to its repository's latest release, by the commit of its tag. This
970
+ replaces Dependabot's version updates, whose pull requests can add no
971
+ pubrel row and get no SonarQube Cloud token, so they failed `pubrel
972
+ check` and the sonar job. Major releases come too, gated on CI like
973
+ everything else here. A pin by tag, to a branch (`# main`) or of a
974
+ pre-release stays, as does one whose latest release or tag cannot be
975
+ read, with a warning. The workflows `pubrules sync` writes move with
976
+ pubrules;
977
+ 3. the other crates' updates (`pubrules crates`) that `cargo vet` covers
978
+ with an audit, adding no exemption, and that `cargo deny` passes. The
979
+ body lists each update skipped with what `cargo vet suggest` says it
980
+ needs;
981
+ 4. the npm packages, each to the newest version its range in
982
+ `package.json` allows (`npm update --package-lock-only
983
+ --ignore-scripts`);
984
+ 5. `tests/requirements.lock`, re-resolved from `requirements.txt` (`pubrules
985
+ lock`).
986
+
987
+ Each commit regenerates `SUPPLY-CHAIN.md` where there is one and records an
988
+ `internal` pubrel row for each package it changes. An open pull request is
989
+ updated, never a second one opened, by pubfleet's loop.
990
+
991
+ ### Update and security settings
992
+
993
+ A repository chooses what its nightly does in `pubrules.json`, per language
994
+ (`rust`, `node`, `python`; each applies where the repository has that
995
+ ecosystem's lock), and for the third-party GitHub Actions (`actions`):
996
+
997
+ ```json
998
+ {
999
+ "kind": "utility",
1000
+ "update": { "rust": true, "node": true, "python": false },
1001
+ "nightly": { "pins": { "crates": ["some-crate"] } },
1002
+ "security": {
1003
+ "fuzz": { "rust": true },
1004
+ "dependabot": { "schedule": "weekly", "ecosystems": ["github-actions"] },
1005
+ "sonar": { "args": "-Dsonar.exclusions=vendor/**" }
1006
+ }
1007
+ }
1008
+ ```
1009
+
1010
+ | Setting | Default | Off means |
1011
+ |---|---|---|
1012
+ | `update.<language>` | `true` | the nightly pull request leaves that language's dependencies alone; `"update": false` turns every language off, and the actions, leaving the pub* pins alone |
1013
+ | `update.actions` | `true` | the nightly leaves the third-party GitHub Actions alone, and the managed `dependabot.yml` keeps Dependabot's version updates of them |
1014
+ | `nightly.pins.crates` | three crates, with a warning | the crates the nightly moves with the pins, whatever `cargo vet` says, rather than one at a time; `[]` is none. `pubrules sync --check` refuses any other key in `nightly` or `nightly.pins` |
1015
+ | `security.fuzz.<language>` | `true` | a scheduled run fuzzes as briefly as any other: `rust-ci.yml` runs cargo-fuzz for `fuzz-seconds` instead of `fuzz-seconds-scheduled`, and `python-ci.yml` and `node-ci.yml` give each property test `fuzz-runs` inputs instead of `fuzz-runs-scheduled` (see [Property tests](#property-tests)) |
1016
+ | `security.dependabot` | weekly, `github-actions` | `pubrules sync` writes `.github/dependabot.yml` from `schedule` (`daily`, `weekly` or `monthly`), `ecosystems` (names, at the root, or Dependabot's own `{"package-ecosystem", "directory"}`) and `options` (any other Dependabot setting, on every entry). `false` leaves the file to the repository. The languages are the nightly's to update, so the default leaves them out. Every `github-actions` entry ignores the owner's `pubrules/*` and `pubrel/*` workflows and actions, whose pins move with `pubrules bump` alone; ignores in `options` are kept. While the nightly moves the actions (`update.actions`), every `github-actions` entry also sets `open-pull-requests-limit` to 0: Dependabot opens no version updates of them, and its security updates still come |
1017
+ | `security.sonar` | none | `args` adds SonarQube Cloud properties to every sonar job's scan, after the `sonar-args` input; `organization` is the SonarQube Cloud organization key, by default the GitHub owner in lower case |
1018
+
1019
+ A setting pubrules does not know stops the nightly with a message, rather
1020
+ than being ignored.
1021
+
1022
+ Advisory checks have no setting. Every run of `rust-ci.yml`, `node-ci.yml`
1023
+ and `python-ci.yml`, the nightly included, checks the advisories and fails
1024
+ on a finding: OSV-Scanner reads every lockfile in the repository against
1025
+ the OSV database (RustSec, GitHub, PyPI and npm advisories), and each
1026
+ language adds its own check: cargo deny, `npm audit` of `package-lock.json`,
1027
+ or pip-audit of the hash-locked requirements. On a public repository's
1028
+ pull request, GitHub's dependency review also fails a change that brings
1029
+ in a vulnerable version. Its license check leaves out the owner's own
1030
+ reusable workflows and actions, for which GitHub reads no license: `pubrules
1031
+ sync` lists those the repository's workflows call in
1032
+ `.github/dependency-review-licenses.txt`, and the review takes only the
1033
+ owner's from it. The pub* pins also always come,
1034
+ so a governed repository keeps up with the standard. A repository's own CI
1035
+ runs on a schedule when its `ci.yml` has a `schedule:` trigger; the
1036
+ settings say what that run does.
1037
+
1038
+ ### Property tests
1039
+
1040
+ Python and Node fuzz with property tests: a test states what holds for
1041
+ every input, and the library generates inputs to break it, shrinking any
1042
+ failure to a small example. Python's is [Hypothesis](https://hypothesis.readthedocs.io),
1043
+ which `tests/requirements-pubrules.txt` pins for every package; Node's is
1044
+ [fast-check](https://fast-check.dev), which a package adds to its own
1045
+ `devDependencies`.
1046
+
1047
+ Each property tries `PUBRULES_FUZZ_RUNS` inputs, which `python-ci.yml` and
1048
+ `node-ci.yml` set: `fuzz-runs` (100) on every push and pull request, and
1049
+ `fuzz-runs-scheduled` (10000) on a scheduled run unless
1050
+ `security.fuzz.<language>` is `false`. pubrules' pytest plugin reads it for
1051
+ Hypothesis, with no deadline. fast-check reads no variable of its own, so a
1052
+ setup file the test command loads (`node --test --import ./tests/setup.mjs`,
1053
+ or Vitest's `setupFiles`) does:
1054
+
1055
+ ```js
1056
+ import fc from "fast-check";
1057
+ fc.configureGlobal({ numRuns: Number(process.env.PUBRULES_FUZZ_RUNS) || 100 });
1058
+ ```
1059
+
1060
+ A failing property prints the input that broke it; Hypothesis also prints a
1061
+ `@reproduce_failure` blob that replays it exactly.
1062
+
1063
+ ## Locking
1064
+
1065
+ `pubrules lock` resolves with pip's own resolver (`pip install --dry-run
1066
+ --report`) and needs nothing else. The lock pins the pubrules wheel by URL and
1067
+ sha256: a release carries the wheel as an asset, and `pip install
1068
+ --require-hashes` verifies it.
1069
+
1070
+ ### A wheel mirror, for when GitHub's release downloads fail
1071
+
1072
+ A wheel pinned by a GitHub release URL fails to install whenever GitHub's
1073
+ release downloads do, and pip retries no 504. `tests/install-lock`, which
1074
+ every managed install of a lock goes through (pubrules.mk's `venv`, the
1075
+ reusable workflows' `sync --check` steps), tries the install three times,
1076
+ 15 s apart. With a wheel mirror in pubrules.json, a fourth try takes each
1077
+ wheel the lock pins by a GitHub release URL from the mirror instead:
1078
+
1079
+ ```json
1080
+ "mirror": {"wheels": "https://storage.sustenaut.eu/wheels"}
1081
+ ```
1082
+
1083
+ The mirror serves each file at `<base>/f/<sha256>/<file>.whl`, so a lock
1084
+ line alone gives its address, and the hashes stay as they are: pip checks
1085
+ every file, and the mirror only has to be there, never trusted.
1086
+ pip-audit's last try reads the locks rewritten the same way
1087
+ (`tests/install-lock --rewrite LOCK`), and `./pubrules` fetches its own wheel
1088
+ (by the sha256 tests/requirements.lock pins) and deploy.providers' wheels
1089
+ from the mirror when GitHub fails to give them. Without the setting, the
1090
+ installs only retry, and `./pubrules` is as before.
1091
+
1092
+ With a PyPI mirror too, the fourth try takes every other package from its
1093
+ simple repository index (PEP 503) instead of PyPI, again checked against
1094
+ the lock's hashes:
1095
+
1096
+ ```json
1097
+ "mirror": {"wheels": "https://storage.sustenaut.eu/wheels", "pypi": "https://storage.sustenaut.eu/pypi"}
1098
+ ```
1099
+
1100
+ Filling the mirror is the mirror's own job. For storage.sustenaut.eu, an
1101
+ hourly workflow in Sustenaut/storage copies every wheel attached to a
1102
+ release of Sustenaut's public repositories, and the PyPI files and
1103
+ Terraform providers the repositories' locks pin.
1104
+
1105
+ ## CI
1106
+
1107
+ ```yaml
1108
+ jobs:
1109
+ ci:
1110
+ uses: Sustenaut/pubrules/.github/workflows/rust-ci.yml@<commit> # v0.1.0 (or python-ci.yml, node-ci.yml)
1111
+ secrets: { SONAR_TOKEN: '${{ secrets.SONAR_TOKEN }}' } # by name, not inherit
1112
+ release:
1113
+ needs: ci
1114
+ uses: Sustenaut/pubrel/.github/workflows/release.yml@<commit> # v0.1.0
1115
+ with: { pubrel-version: v0.1.0 }
1116
+ permissions: { contents: write }
1117
+ ```
1118
+
1119
+ Pin each one to the full commit its release's tag names, with the version in a comment, as above, rather than to the tag (`@v0.1.0`), which can be moved: SonarQube Cloud flags a tag pin (S7637). `pubrules bump` and the nightly write pubrules' pins this way, and every reader still takes a pin by tag.
1120
+
1121
+ - **`rust-ci.yml`:** runs every check the standard requires. A `plan` job builds the hash-locked venv, runs `make sync-check`, and asks `pubrules required` which make targets each job runs. Then:
1122
+ - `gates` runs the required gate targets, then any the `gates` input adds;
1123
+ - `test` runs `cargo test` on Linux, macOS and Windows (`test-args` adds arguments);
1124
+ - `functional` runs the required functional targets, then any the `functional` input adds, optionally with extra apt packages and a released `pub`;
1125
+ - `msrv` runs `make msrv MSRV=<the lowest rust-version stated>` on that toolchain;
1126
+ - `fuzz` runs `make fuzz-smoke` on nightly: the inputs that once found a bug, then each target for `fuzz-seconds` (5 s, so the merge queue waits about a minute, as for the other jobs), and for `fuzz-seconds-scheduled` (900 s) on a schedule unless `pubrules.json` sets `"security": { "fuzz": { "rust": false } }`;
1127
+ - `cross` runs `cargo test` under qemu on `cross-targets`: i686 and s390x by default, or aarch64 `-unknown-linux-gnu`, with `cross-test-args`;
1128
+ - `audit` runs `make deny` and `make vet`, with `cargo-deny-version` and `cargo-vet-version`;
1129
+ - when the caller also runs on a `schedule`, those runs test on the latest stable and beta Rust (`scheduled-toolchains`).
1130
+
1131
+ On a pull request that touches no Rust code (`*.rs`), Cargo files (`Cargo.toml`, `Cargo.lock`, the toolchain pin), `fuzz/` or workflow files (`.github/workflows/`), the plan skips `fuzz` and `cross`, the slow emulated jobs: a documentation or `pubrules.json` change does not wait for them. A release pull request (a `release/` branch), a push to main and the nightly run everything. `pubrules required --event E --head-ref B --changed-files F` decides, and says why on stderr.
1132
+
1133
+ The `gates` and `functional` inputs can only add targets. The `msrv` and `fuzz` inputs are ignored: those jobs run because the standard requires them. Every job reports through `passed`, the one check a ruleset needs. The `sonar` job, in every workflow that has one and in `job-sonar.yml`, waits for SonarQube Cloud's quality gate (`sonar.qualitygate.wait`, for at most 300 seconds), so a failing gate fails the job and `passed` with it, rather than showing only on the SonarCloud app's own check. Without a `SONAR_TOKEN` it still passes with a notice.
1134
+ - **`python-ci.yml`:** takes its commands as inputs (`setup`, `test`, `browser-test`), so a repository with its own entry point keeps it. A non-empty `browser-test` adds a job that installs Playwright's Chromium. The coverage it writes to `browser-coverage-report` (by default `coverage/`) reaches SonarQube Cloud with the functional job's, and the sonar job waits for it. The `audit` job checks `audit-requirements` (by default `tests/requirements.lock`) with pip-audit on every run.
1135
+ - **`node-ci.yml`:** for a Node package. It installs from `package-lock.json` with `npm ci --ignore-scripts`, so no dependency runs code by being installed, checks pubrules' managed files from `tests/requirements.lock`, and runs `npm test`. The `audit` job runs `npm audit --package-lock-only` on every run and fails on any advisory, development dependencies included. A non-empty `browser-test` adds a job that installs Playwright's Chromium with `npx --no-install`, which runs only what the lock installed. The coverage it writes to `browser-coverage-report` (by default `coverage/`, LCOV) reaches SonarQube Cloud with the test job's, and the sonar job waits for it. The commands are inputs (`setup`, `test`, `browser-test`, `browser-setup`). A repository with a `ci` block in pubrules.json gets the same jobs generated instead (below).
1136
+
1137
+ ### Generated CI: only the jobs a repository runs
1138
+
1139
+ A shared reusable workflow has to skip the jobs a repository doesn't use, and GitHub lists each one as skipped. A repository of any kind avoids that with a `ci` block in `pubrules.json`. `pubrules sync` then writes one workflow per event, and each workflow calls only the jobs that event runs. Each job is its own reusable workflow (`job-node-test.yml`, `job-rust-gates.yml`, `job-sonar.yml` and so on) at this pubrules' release, so the Actions pins still live in pubrules. `pubrules init` writes `"ci": {}`, and `pubrules new` `"ci": {"release": {"pubrel": "X.Y.Z"}}`, at the release above.
1140
+
1141
+ Sync pins each one, and pubrel's release workflow, to the full commit of the release's tag, with the version in a comment, so SonarQube Cloud's S7637 (a reusable workflow pinned to a tag, which can move) needs no exception:
1142
+
1143
+ ```yaml
1144
+ uses: Sustenaut/pubrules/.github/workflows/job-rust-test.yml@0f3574a72707a46bae149d3ed7a4644b4837795a # v0.15.2
1145
+ ```
1146
+
1147
+ Usually neither needs the network. pubrules' commit is in its wheel: the release CI writes the tag's commit into the package (`release-commit`) before it builds the wheel. A source checkout of pubrules has none, and pins by tag. pubrel's commit is the one the repository's workflows already pin at that version; failing that, sync reads it once from pubrel's tags with `git ls-remote`, and when it cannot, pins by tag with a warning. Workflows written before, pinned by tag, still read and check as before.
1148
+
1149
+ Whose pubrules and pubrel these are is set in one place, `OWNER` in `src/pubrules/refs.py`: `Sustenaut`, since both moved there from `schryer`. Every repository moves to it on its next `pubrules sync`, and the nightly moves its hand-written `*-ci.yml` and pubrel pins with `pubrules pins` (`pubrules bump` too). A repository can name another owner first with `"workflows_owner": "sustenaut"` in pubrules.json; it also names the repository `git ls-remote` reads pubrel's tags from. `conform`, the nightly and the audit read a pin under any owner, so one still under the old owner keeps working.
1150
+
1151
+ ```json
1152
+ "ci": {
1153
+ "events": ["pr", "queue", "main", "nightly"],
1154
+ "cron": "17 3 * * *",
1155
+ "with": {"browser-test": "npm run test:browser", "coverage-report": "coverage/",
1156
+ "sonar-args": "-Dsonar.tests=test"},
1157
+ "jobs": {"review": false, "sonar": {"events": ["pr", "main"]}},
1158
+ "release": {"pubrel": "0.5.4"},
1159
+ "tools": [{"crate": "some-cli", "git": "https://github.com/example-org/some-cli", "tag": "v1.2.3"}]
1160
+ }
1161
+ ```
1162
+
1163
+ - **`events`:** which workflows to write. `pr` writes `pr.yml` (pull requests), `queue` writes `queue.yml` (the merge queue's runs of them, `merge_group`), `main` writes `main.yml` (pushes to main), and `nightly` writes `nightly.yml` (`cron`, or by hand). The default is pr, queue and main, and all four for Rust. The queue runs every job a pull request runs, and the heavy ones besides (Rust's `msrv`, `fuzz` and `cross`), so each push to a pull request gets its answer sooner while nothing merges before the heavy jobs pass. Where the queue would run nothing a pull request does not (Node, Python and service repositories, by default), sync writes no `queue.yml` and `pr.yml` runs on `merge_group` too. A repository without a merge queue (a user's, or a private one) leaves `queue` out, so its pull requests run the heavy jobs themselves.
1164
+ - **`with`:** the jobs' inputs, the same ones `python-ci.yml`, `node-ci.yml`, `rust-ci.yml` and `service-ci.yml` take. Each input goes to every job that takes it, and one that no job takes stops sync.
1165
+ - **`jobs`:** narrows the events a job runs on, or drops it with `false` (a private repository drops `review`, since GitHub's dependency graph serves only public ones). By default every job runs on every event, except `review`, which runs on pull requests only, and Rust's `msrv`, `fuzz` and `cross`, which run everywhere but on pull requests. `browser` runs only when `with` gives a `browser-test`.
1166
+ - **`tools`:** Rust's: what the functional suite drives. Each `crate` is installed from its `git` repository at its `tag` with `cargo install --locked`, and the nightly moves the tag to that repository's latest release.
1167
+ - **`runs-on`:** the runners, for a repository with self-hosted ones. A label (`"runs-on": "my-runners"`) runs every job there; an object of labels by job name, with `default` for the rest (`{"default": "my-runners", "review": "ubuntu-latest"}`), places them one by one. Sync passes it to each job as its `runs-on` input (every reusable workflow, `python-ci.yml`, `node-ci.yml`, `rust-ci.yml` and `service-ci.yml` too, takes one, `ubuntu-latest` by default) and writes it into `tested`, `passed` and `site`. Rust's `test` runs on its `os-matrix` instead. pubrel's release workflow takes it (`release` places it on its own) from pubrel 0.7.0, which installs Rust on a runner without it. An older pubrel's runs on GitHub's runners. Without it nothing is written, and every job runs on `ubuntu-latest`. The runner must have what `ubuntu-latest` gives these jobs (git, curl, jq, python3 with venv, gh, shellcheck, unzip, a C toolchain, Docker).
1168
+ - **`language`:** a utility's, `node` or `python`. Without it, a `package.json` with no `pyproject.toml` beside it means Node. A rust, service or content repository's CI is its kind's.
1169
+ - **`release`:** adds pubrel's release workflow to `pr.yml`, `queue.yml` and `main.yml`, after `passed`. It uses the pubrel `pubrel` names, or where it names none the one the workflows sync wrote already pin, or else pubrel's latest release (below), and `with` adds inputs (Rust's always checks semver, `semver-checks-version: 0.51.0`). `false` leaves it out. A service deploys rather than releases, so it has none, and a content repository, which pubrules neither releases nor deploys, has none either. `{"uses": "local"}` calls the repository's own `.github/workflows/release.yml` in place of pubrel's published one, as pubrel does, so a change to its release workflow is tested before it ships; only `with` goes with it. The nightly moves `release.pubrel` in pubrules.json, writing it there where it named none, then runs `pubrules sync`.
1170
+
1171
+ Neither the merge queue nor `main.yml` tests again what an earlier run already tested. A pull request up to date with main merges as the very files its own run tested, and merging moves main to the very commit the queue tested. So `main.yml`, and `pr.yml` where the queue runs it (there is no `queue.yml`), start with `tested` (`job-tested.yml`, `ci / tested`). In the queue and on main, it looks for a successful run of that workflow, on a pull request or in the queue, whose commit has this commit's tree. A run that skipped its own tests names, in a notice, the run it took them from, and that run counts, so long as its artifacts have not expired. When there is one, every job that run ran is skipped (a job only main runs still runs), and `passed` and the release follow. On main, `sonar` still runs, reading the coverage that run uploaded, because SonarQube Cloud measures main from a push to it. The merge queue never scans: SonarQube Cloud analyses pull requests and main, and refuses the queue's `gh-readonly-queue` branch. The pull request's run scanned the change, and main's push scans the merge, so `sonar` does not run on `merge_group` in `pr.yml`, `passed` takes that skip, and a Rust `queue.yml` has no `sonar` at all. So a ruleset with a merge queue must not require SonarQube Cloud's own check, `SonarCloud Code Analysis` (sync refuses it), or the queue waits for that check forever; `ci / sonar` still fails `ci / passed` on a pull request's quality gate. `ci / passed` already takes the skip. When there is none (a pull request's own run, main moved on in between, several pull requests merged together, a repository without the queue, or a commit that reached main some other way) every job runs as it would without `tested`. A Rust crate's `queue.yml` runs jobs its pull requests do not, so its queue tests everything. The nightly always runs everything.
1172
+
1173
+ A Rust repository runs the jobs the Rust crate standard asks for here, worked out at sync time from the rules and `pubrules.json`'s exceptions: `gates`, `test`, `functional`, `msrv`, `fuzz`, `cross` and `audit` as required, beside `osv`, `review` and `sonar`, and `toolchains` (the latest stable and beta Rust) on the nightly. Sync writes each job's required make targets into the workflow (`required`), so an exception added or expired shows as a change there, and `make sync-check` in `gates` fails until `pubrules sync` writes it. An empty `cross-targets` (`"[]"`) drops `cross`. `msrv`, `fuzz` and `cross` run in the merge queue rather than on each push to a pull request (unless `events` leaves out `queue`). On a pull request that touches no Rust code, Cargo files, `fuzz/` or workflow files, `fuzz` and `cross` pass at once with a notice (from `pubrules required`, which says `slow=false`) rather than being skipped; release pull requests, pushes and the nightly run them in full.
1174
+
1175
+ Uploading a coverage report and restoring or saving a cache only help a run: none of them fails a job. GitHub's artifact and cache services can refuse a run (when the account's Actions billing is blocked they answer with an HTML page, on self-hosted runners too), so every `upload-artifact` of a report and every `actions/cache` step in pubrules' workflows, and every restore and save in `actions/cache`, runs with `continue-on-error`, and the workflow steps stop trying after five minutes. A test that fails still fails its job; a refused upload only leaves the scan without that coverage.
1176
+
1177
+ A service runs `checks` (the sync check and shellcheck) and `sonar`, and `terraform` and `tests` when `with` gives a `terraform-dir` and a `test`. Its tests hand `sonar` the coverage they write to `coverage-report` (by default `coverage/`, Cobertura XML or LCOV `lcov.info`). `with`'s `apt-packages` names Ubuntu packages its tests job installs first, through `actions/apt-install`, from the Actions cache when an earlier run installed them (`"apt-packages": "tippecanoe"`); a content repository's tests take it too. A private service drops the scan with `"jobs": {"sonar": false}`. A content repository runs `checks` (shellcheck on `**/*.sh` unless `with` gives `shellcheck`) and, when `with` gives a `test`, `tests`, and has no `sonar`.
1178
+
1179
+ A repository that deploys a static site with pubhost's `deploy-static` also gets a `site` job in `pr.yml` (`ci / site`, part of `ci / passed`), so a site that would fail to deploy fails the pull request instead of the deploy after merge. It checks the repository out, builds the site, and runs the `deploy-static` the repository's own deploy workflow pins, as it pins it, with `check-only: 'true'`, which runs its site check and deploys nothing, so it needs no secret. The job comes when any workflow of the repository's own uses `deploy-static`, or pubrules.json has a `site` block, which then needs such a workflow to take the pin from:
1180
+
1181
+ ```json
1182
+ "site": {"check_dir": "public", "pr_build": "npm run build:sample", "build": "npm run build",
1183
+ "url": "https://example.eu/"}
1184
+ ```
1185
+
1186
+ - **`check_dir`:** the directory to check, inside the repository. Without it, the `dir` the deploy workflow gives `deploy-static`.
1187
+ - **`pr_build`:** the command that builds the site for the check, such as a build from a small sample of its data where the full build is slow. Without it, `build`; without either, the directory is checked as it is in the repository.
1188
+ - **`url`:** the site's https:// address, so the check finds its og:image files.
1189
+
1190
+ Each is one line of text, and sync refuses any other key.
1191
+
1192
+ The checks keep the names a ruleset requires: each job is named `ci`, so its checks read `ci / test`, `ci / sonar` and so on. Every workflow ends in `ci / passed`, which passes only when every job succeeded. The generated workflows are managed files, so `pubrules sync --check` fails when one is edited, and also while a hand-written `ci.yml` is still beside them. A repository without a ci block keeps its own `ci.yml`, which can still call `rust-ci.yml`, `python-ci.yml`, `node-ci.yml` or `service-ci.yml`.
1193
+
1194
+ ### SonarQube Cloud
1195
+
1196
+ Public code integrates with SonarQube Cloud, whatever its kind: `rust-ci.yml`, `python-ci.yml`, `node-ci.yml` and `service-ci.yml` each run a `sonar` job, part of `passed`, and so does the CI `pubrules sync` writes for every kind but content, which holds no code. Only a private repository, which SonarQube Cloud does not analyse for free, leaves it out (`"jobs": {"sonar": false}`). Given a `SONAR_TOKEN` secret, passed by name (`secrets: { SONAR_TOKEN: '${{ secrets.SONAR_TOKEN }}' }`, since `secrets: inherit` reaches only a workflow of the caller's own owner and GitHub drops it without a word for pubrules' once the owners differ), it sends the code to SonarQube Cloud as the project `OWNER_REPO` (the owner as GitHub spells it) in the organization whose key is the owner in lower case, or `security.sonar.organization` in pubrules.json, with the full history so it can tell new code from old; `sonar-args` adds properties. Without a token, as in a private repository or a pull request from a fork, it passes with a notice. To turn it on for a public repository:
1197
+
1198
+ 1. In SonarQube Cloud, analyse the repository as a new project in the organization whose key is its GitHub owner in lower case (or the one `security.sonar.organization` names), keeping the key `OWNER_REPO`.
1199
+ 2. Under the project's Administration, Analysis Method, turn Automatic Analysis off: the two cannot run together.
1200
+ 3. Add the token as the repository's `SONAR_TOKEN` Actions secret.
1201
+
1202
+ The default quality gate asks for 80% coverage on new code, and a scan without a coverage report counts it as 0%, so each workflow hands the sonar job one:
1203
+
1204
+ | Workflow | Report | Written by |
1205
+ |---|---|---|
1206
+ | `rust-ci.yml` | `coverage/lcov.info` | `make coverage`, which the functional job runs in place of `make functional` when there is a token: the Rust tests and the Gherkin suite on a build cargo-llvm-cov instruments (`cargo-llvm-cov-version`) |
1207
+ | `rust-ci.yml` | `coverage/*.xml` (Cobertura) | any of the `functional` targets, for a repository's Python, such as coverage.py's `coverage xml -o coverage/scripts.xml` (run it after `make coverage`, which empties `coverage/`) |
1208
+ | `python-ci.yml` | `coverage-report`, by default `coverage/coverage.xml` (Cobertura) | the `test` command, such as coverage.py with `patch = ["subprocess"]`, which also measures the programs the suite starts (pubrules' own `make functional` does this) |
1209
+ | `node-ci.yml` | `coverage-report`, by default `coverage/lcov.info` | the `test` command, such as `node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info` |
1210
+ | `service-ci.yml` | `coverage-report`, by default `coverage/`: Cobertura `*.xml` or LCOV `lcov.info` | the `test` command, as for Python or Node |
1211
+
1212
+ A test command that writes no report leaves the scan as it was.
1213
+
1214
+ In the CI `pubrules sync` writes, the scan also learns which code is tests, so SonarQube Cloud does not warn that files "look like test code" while `sonar.tests` is unset. Sync gives the sonar job a `layout` from the directories the repository has:
1215
+
1216
+ | Language | `sonar.sources` | `sonar.tests` |
1217
+ |---|---|---|
1218
+ | Python | `src` | `tests` |
1219
+ | Rust | `src`, `crates` (a workspace) | `tests`, `fuzz`, `benches` |
1220
+
1221
+ Each lists only the directories that exist, since the scan fails on one that does not. Without any test directory, and for Node and services, sync gives no layout and SonarQube Cloud keeps its defaults. With tests but no code directory, the code is the whole repository less its tests (`sonar.exclusions`), so no file is read as both. `sonar-args` and `security.sonar.args` come after the layout, and the scanner takes the last value a property is given, so a repository's own `sonar.sources` or `sonar.tests` wins. Set both if you set one, or a file can end up in both.
1222
+
1223
+ Every action these workflows use, pubrel's release workflow included, is pinned to a commit, with its version in a comment, and a test fails on one that is not.
1224
+
1225
+ ## Developing
1226
+
1227
+ ```sh
1228
+ make venv # hash-locked environment, this checkout installed editable
1229
+ make check # standard.json current, then the Gherkin suite
1230
+ ```
1231
+
1232
+ The suite drives the plugin through pytest's `pytester`. Each scenario
1233
+ builds a throwaway suite, runs it in a subprocess, and judges what pytest
1234
+ reports. It drives the command in a scratch repository. pubrules is its own
1235
+ first consumer: its CI runs through `python-ci.yml` from this checkout, and
1236
+ it is released with [pubrel](https://github.com/Sustenaut/pubrel). Its
1237
+ package publet, `pkg.pubrules`, lives in `corpus/`.
1238
+
1239
+ ## Licence
1240
+
1241
+ Apache-2.0: see [`LICENSE`](LICENSE).