Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AUDIT.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -22,6 +22,7 @@ Three dimensions, each independently checkable:
## 1. Settings and Rulesets

```sh
# From a hub checkout, which hosts the script rather than this repo carrying a copy.
repo-config/configure.sh check ptr727/Blog release
```

Expand Down
2 changes: 1 addition & 1 deletion TODO.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -155,7 +155,7 @@ Each of these was hit or nearly hit, and each is cheap to re-trip.
- **`content/` is an imported archive.** Prose, spelling, and style sweeps do not reach it, and `cspell.json` ignores it deliberately.
- **A gate is trusted only after it has been demonstrated failing.** Every gate here has been. A list-driven check also needs a length floor, or a truncated list passes while checking almost nothing.
- **Do not name any workflow `build-*-task.yml`** while the repo declares `source-only`, since `detect` is literally `["no build-*-task.yml"]`.
- **Do not edit `.markdownlint-cli2.jsonc`, `repo-config/configure.sh`, or the two ruleset payloads.** They are carried verbatim and byte-matched against the hub. Scope a glob in the workflow instead. A reviewer finding a real defect in one of them is answered by declining locally and filing it at the hub, never by editing the file to satisfy the review.
- **Do not edit `.markdownlint-cli2.jsonc`or the two ruleset payloads.** They are carried verbatim and byte-matched against the hub. `repo-config/configure.sh` was in this list until it was retired: the hub hosts it and this repo reaches it there, so there is no local copy to edit or to protect. Scope a glob in the workflow instead. A reviewer finding a real defect in one of them is answered by declining locally and filing it at the hub, never by editing the file to satisfy the review.
- **The hub's `main` can promote while a convergence pull request is open**, so ground truth moves underneath work that was correct when it started. It happened twice in one session on 2026-08-03, and the second time added drift the branch could not have known about. Re-run the audit against the hub ref actually carried before claiming convergence, and name that ref in the change, or the claim ages into a false one.
- **Before believing a negative, establish that the check could have produced a positive.** An empty result and a clean result are the same bytes, so the question is never "did it find anything" but "could it have". The instances below are the same failure in different costumes, some of which cost a false pass and one of which has not happened yet. It is stated as a demand for evidence rather than as a warning to be careful because *be careful* has no step to perform and *prove the check can fire* does.
- **A query that cannot see its target.** A review-thread poll blind to suppressed findings, a reviewer filter written in the wrong API's login form, an audit loop whose `jq` path had moved, and a journal grep for `Started` from an account not in `adm` or `systemd-journal`, where the lines exist and are not shown to it. Assert the query matched before reading what it returned, which is what `jq -e` and a non-empty check are for.
Expand Down
6 changes: 3 additions & 3 deletions repo-config/README.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,9 +2,9 @@

Repository and branch configuration held as committed files, kept out of `.github/` (which holds the GitHub-consumed configuration: workflows, Dependabot).

- `main.json` plus one `develop` variant: the branch rulesets as the writable API subset (`name`, `target`, `enforcement`, `bypass_actors`, `conditions`, `rules`). The `develop` payload is `develop.json` (`release` repos) or `operational/develop.json` (`operational` repos). These are the canonical expected payloads that the self-audit (`AUDIT.md`) diffs the live rulesets against.
- `main.json` plus one `develop` variant: the branch rulesets as the managed part of the writable API subset (`name`, `target`, `enforcement`, `conditions`, `rules`). The `develop` payload is `develop.json` (`release` repos) or `operational/develop.json` (`operational` repos). These are the canonical expected payloads that the self-audit (`AUDIT.md`) validates the live rulesets against, by asserting rule presence, merge methods and required checks rather than diffing bytes, so a ruleset GitHub has normalized does not read as drift. `bypass_actors` is writable and deliberately unmanaged, so no payload declares one and nothing asserts it: who may bypass a ruleset is a human decision taken in the UI, which the configure script preserves on `apply` and reports without asserting on `check`.
- This repo is `release`, so it carries `develop.json` and **not** `operational/develop.json`. The operational variant takes direct signed pushes with no PR gate, which is the wrong ruleset here. See "Rulesets" below.
- `configure.sh`: two modes over the GitHub API. `configure.sh apply [owner/repo] [release|operational]` creates-or-updates the settings, the Dependabot security features, and the rulesets idempotently (a full-payload update). `configure.sh check [owner/repo] [release|operational]` is the read-only inverse and exits non-zero on any drift, with the ruleset and settings assertions driven by the committed payloads so they stay repo-agnostic (rule presence, merge methods, and required checks, not a byte diff, so a GitHub-normalized stored ruleset does not false-positive). The command defaults to `apply`, the repo to the current one, and the model to the registry `workflowModel` lookup (or, absent a registry, inference from the carried `develop` payload, where an ambiguous layout aborts rather than guesses). The model may be passed as the sole positional (`configure.sh check release`).
- `configure.sh`: **hosted in the hub and run from a hub checkout, not carried here**, per the Hub-Hosted Tooling rule in `GOVERNANCE.md`. The payloads above are what this repo is audited against and stay with it. The script holds nothing per-repo and is one copy for the fleet, so a carried copy would only be current until the next fix to it. Name the target repository explicitly, since the command defaults to whichever repository the shell is sitting in. Two modes over the GitHub API. `repo-config/configure.sh apply ptr727/Blog release` creates-or-updates the settings, the Dependabot security features, and the rulesets idempotently. `repo-config/configure.sh check ptr727/Blog release` is the read-only inverse and exits non-zero on any drift, with the assertions driven by the committed payloads rather than a byte diff, so a GitHub-normalized stored ruleset does not false-positive.

## Rulesets

Expand All@@ -23,7 +23,7 @@ Publish credentials required per mechanism are enumerated in `spec/secrets.json`

## Repo Settings

The fleet-standard general settings live in [`settings.json`][settings-json] and are applied idempotently by `configure.sh apply` alongside the rulesets (`gh api PATCH /repos/{owner}/{repo}`). The two settings that depend on per-repo state, `has_discussions` (visibility) and `default_branch` (main-must-exist), are computed by the script, not stored in the file. `configure.sh apply` also enables Dependabot vulnerability alerts and automated security updates, fleet policy applied via the API rather than a `settings.json` key. `configure.sh check` validates all of these and exits non-zero on drift.
The fleet-standard general settings live in [`settings.json`][settings-json] and are applied idempotently by `repo-config/configure.sh apply ptr727/Blog release` alongside the rulesets (`gh api PATCH /repos/{owner}/{repo}`). The two settings that depend on per-repo state, `has_discussions` (visibility) and `default_branch` (main-must-exist), are computed by the script, not stored in the file. That same `apply` also enables Dependabot vulnerability alerts and automated security updates, fleet policy applied via the API rather than a `settings.json` key. `repo-config/configure.sh check ptr727/Blog release` validates all of these and exits non-zero on drift.

- **Default branch `main`** (the script sets it only when a `main` branch exists, never pointing the default at a missing branch).
- **Merge methods**: `Allow merge commits` and `Allow squash merging` on, **rebase off**, and each branch ruleset then picks its method (merge on `main`, squash on `develop`).
Expand Down
Loading