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.
- pubrules/__init__.py +14 -0
- pubrules/audit.py +116 -0
- pubrules/audit_draft.py +295 -0
- pubrules/audit_prepare.py +1128 -0
- pubrules/cache.py +319 -0
- pubrules/cbor.py +45 -0
- pubrules/ci.py +910 -0
- pubrules/cli.py +1069 -0
- pubrules/conform.py +295 -0
- pubrules/doc_coverage.py +235 -0
- pubrules/freshness.py +75 -0
- pubrules/gherkin.py +348 -0
- pubrules/hooks.py +59 -0
- pubrules/hosting.py +372 -0
- pubrules/ignores.py +86 -0
- pubrules/new.py +242 -0
- pubrules/nightly.py +1002 -0
- pubrules/paths.py +32 -0
- pubrules/protect.py +596 -0
- pubrules/providers.py +129 -0
- pubrules/refs.py +213 -0
- pubrules/release-commit +1 -0
- pubrules/releases.py +107 -0
- pubrules/repos.py +67 -0
- pubrules/ruleset.json +43 -0
- pubrules/secrets_config.py +165 -0
- pubrules/security.py +134 -0
- pubrules/service_needs.py +467 -0
- pubrules/standard.json +635 -0
- pubrules/standard.py +266 -0
- pubrules/supply_chain.py +188 -0
- pubrules/tag-ruleset.json +14 -0
- pubrules/templates/common/AGENTS.md +32 -0
- pubrules/templates/common/pubrules +26 -0
- pubrules/templates/common/tests/features/repository.feature +11 -0
- pubrules/templates/common/tests/install-lock +65 -0
- pubrules/templates/common/tests/pytest.ini +4 -0
- pubrules/templates/common/tests/requirements-pubrules.txt +17 -0
- pubrules/templates/common/tests/requirements.txt +3 -0
- pubrules/templates/common/tests/steps/test_repository.py +14 -0
- pubrules/templates/deploy/pubdeploy +28 -0
- pubrules/templates/new-rust/CHANGELOG.md +3 -0
- pubrules/templates/new-rust/Cargo.toml +46 -0
- pubrules/templates/new-rust/LICENSE +202 -0
- pubrules/templates/new-rust/Makefile +18 -0
- pubrules/templates/new-rust/README.md +34 -0
- pubrules/templates/new-rust/SECURITY.md +26 -0
- pubrules/templates/new-rust/corpus/corpus.json +11 -0
- pubrules/templates/new-rust/deny.toml +32 -0
- pubrules/templates/new-rust/fuzz/Cargo.toml +23 -0
- pubrules/templates/new-rust/fuzz/fuzz_targets/greet.rs +8 -0
- pubrules/templates/new-rust/fuzz/gitignore +4 -0
- pubrules/templates/new-rust/fuzz/regressions/README.md +4 -0
- pubrules/templates/new-rust/gitignore +10 -0
- pubrules/templates/new-rust/src/lib.rs +91 -0
- pubrules/templates/new-rust/src/main.rs +19 -0
- pubrules/templates/new-rust/supply-chain/audits.toml +4 -0
- pubrules/templates/new-rust/supply-chain/config.toml +23 -0
- pubrules/templates/new-rust/supply-chain/imports.lock +2 -0
- pubrules/templates/new-rust/tests/conftest.py +9 -0
- pubrules/templates/new-rust/tests/features/cli.feature +14 -0
- pubrules/templates/new-rust/tests/steps/test_cli.py +15 -0
- pubrules/templates/new-rust/tests/vectors.rs +30 -0
- pubrules/templates/new-rust/tools/vectors/generate.py +24 -0
- pubrules/templates/python/Makefile +5 -0
- pubrules/templates/python/pubrules-python.mk +47 -0
- pubrules/templates/rust/Makefile +9 -0
- pubrules/templates/rust/pubrules.mk +138 -0
- pubrules/templates/rust/rust-toolchain.toml +8 -0
- pubrules/templates/service/pubsec +27 -0
- pubrules/templates/service/with-secrets +20 -0
- pubrules/templates/service/with-secrets.json +8 -0
- pubrules/variables.py +45 -0
- pubrules-0.48.0.dist-info/METADATA +1241 -0
- pubrules-0.48.0.dist-info/RECORD +79 -0
- pubrules-0.48.0.dist-info/WHEEL +5 -0
- pubrules-0.48.0.dist-info/entry_points.txt +2 -0
- pubrules-0.48.0.dist-info/licenses/LICENSE +202 -0
- 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).
|