From 9b34fb6790cf3e4364b934cc2ac3a1b7901463aa Mon Sep 17 00:00:00 2001 From: Jim Cresswell Date: Thu, 18 Jun 2026 12:44:55 +0100 Subject: [PATCH] docs(governance): add the owner-action checklist (Tier 2) The in-repo gates and audits (including audit_supply_chain) enforce most of the quality bar, but four protections can only be set in GitHub settings: required status checks (Quality gates + Secret scanning), a release-PR token, the Code Quality org preview, and v* tag protection. Consolidates these into a canonical docs/repository-governance.md, with the current ruleset state verified against the live API (PR + CodeQL code_quality + no-deletion + non-fast-forward are enforced; there is no required_status_checks rule and no tag ruleset). Linked from the README so an adopter can audit governance against reality. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 9 ++++++ docs/repository-governance.md | 54 +++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 docs/repository-governance.md diff --git a/README.md b/README.md index 8177596..2080f11 100644 --- a/README.md +++ b/README.md @@ -196,6 +196,15 @@ The bump level is computed by Commitizen with this repo's policy: down; cut the major deliberately via the Release workflow's *Run workflow* button (`increment = MAJOR`). Releases publish to GitHub Releases only (no PyPI). +## Governance + +Most of the quality bar is enforced in code (the `check-ci` gates, the +`repo_audit.py` self-checks, and the SonarCloud PR gate). A few protections live +only in GitHub settings — required status checks, a release-PR token, the Code +Quality preview, and tag protection. Those owner actions are listed in +[docs/repository-governance.md](docs/repository-governance.md); an adopter should +work through them once per repository. + ## Practice Surface - Agent entry point: `.agent/directives/AGENT.md` diff --git a/docs/repository-governance.md b/docs/repository-governance.md new file mode 100644 index 0000000..3f2cf69 --- /dev/null +++ b/docs/repository-governance.md @@ -0,0 +1,54 @@ +# Repository Governance + +This repository enforces most of its quality bar **in code** — the `check-ci` +gate sequence, the `repo_audit.py` self-checks (including `audit_supply_chain`, +which pins every workflow action to a SHA and keeps Dependabot watching both +ecosystems), and the SonarCloud pull-request gate. Those need no manual setup. + +A few protections can only be set in **GitHub repository/organisation settings** +and cannot be expressed in the repo. This page is the canonical owner-action +checklist for them. An adopter of this template should work through it once for +their own repository. + +## Already enforced by the `main` ruleset + +The active "Protect default branch" ruleset already requires: + +- a **pull request** to change `main` (no direct pushes); +- the **CodeQL `code_quality`** check to pass before merge; +- **no branch deletion** and **no force-push** (non-fast-forward) on `main`. + +## Owner actions outstanding + +These are settings changes a repository owner must make by hand. Each closes a +gap the in-repo gates structurally cannot. + +1. **Make CI a real merge gate (highest priority).** + Add **`Quality gates`** and **`Secret scanning (gitleaks)`** to the `main` + ruleset's *required status checks*. Today the ruleset requires a PR and the + CodeQL check, but **not** these two — so `main` can go red and a PR can still + merge. This is the single biggest enforcement gap. + +2. **Give the release PR a token.** + The standing release PR is opened by `GITHUB_TOKEN`, so `ci.yml` does not run + on it and it sits `UNSTABLE` indefinitely (merge it with + `gh pr merge --squash --auto`). Provide `create-pull-request` with a PAT + or GitHub App token so `ci.yml` runs on the release PR; it then goes `CLEAN` + and merges without `--auto`. See [Releases](dev-tooling.md#releases). + +3. **Enable GitHub Code Quality (organisation preview).** + Coverage is uploaded as Cobertura on every PR, but the upload runs with + `fail-on-error: false`, so until the org enables the Code Quality preview it + is a harmless no-op rather than a visible PR signal. See + [Coverage reporting](dev-tooling.md#coverage-reporting). + +4. **Protect release tags.** + Add a tag ruleset for `v*` so release tags cannot be force-moved or deleted. + There is currently no tag ruleset; only the branch ruleset above exists. + +## Why these stay manual + +Repository and organisation settings are owner-controlled and live outside the +tree, so the repo cannot assert them the way it asserts code and config. Keeping +the list here — rather than only in session notes — means a future owner or an +adopter can audit governance against reality without replaying project history.