[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #563 (comment)

What

.github/workflows/release.yml, decision 5 of #563's design, which Brett Heap approved at 2026-10-15T13:32:51Z ("approve all six for #563"). It is adapted from opensoft/openDox-code's release.yml at c94878be. The workflow is dispatch only, with a version input. Nothing is granted at the top level, and each job states its own permissions.

job	runs	checks
build	every dispatch	Refuses unless: the version is X.Y.Z and not 0.0.0; the ref is the annotated tag v<version> whose tag object names this run's commit (read from the forge and from git), or a branch, which is the rehearsal; the commit is on main or release/v<major>.<minor> (compare, by refs/heads/); the checkout is that commit and clean, ignored files included; testpypi and pypi each name a required reviewer and admit only the tag rule v*; the tests job (which tests.yml runs on every trigger since #597) passed in a push or workflow_dispatch run of tests.yml whose head is the commit, read from that run's own jobs; the checkout's own scripts/repo_shape.py tree_digest equals tree_digest_from_gh. Then it installs its tools from a hash lock (--only-binary :all: --require-hashes), extracts the commit twice with git archive into two differently named, differently deep directories, writes the stamp openreposhape/_release.py into each (the committed file with its four assignments given values), and builds a wheel from each with build --wheel --no-isolation at SOURCE_DATE_EPOCH = the commit's time. The two wheels must be one file (cmp). Every file in the wheel except the stamp and .dist-info must equal the commit's own bytes. Every tracked file under src/openreposhape/ must be in it, and nothing else. The stamp may differ from the committed file only in its four lines. METADATA, entry points and LICENSE must match pyproject.toml and the commit, the entry points must declare console_scripts alone, and .dist-info/ must hold exactly METADATA, WHEEL, RECORD, entry_points.txt and licenses/LICENSE. Finally it records the wheel's sha256.
testpypi	v* tag only	Environment testpypi; id-token: write. Checks: the artifact is the recorded digest; at use time, the environment still has a reviewer and the v* rule, and this run holds an approval for it; the tag still names this commit; TestPyPI holds no other file of the version. Then it uploads (pypa/gh-action-pypi-publish, pinned by commit, trusted publishing, skip-existing). Afterwards TestPyPI must serve exactly that digest, not yanked.
install	ubuntu, macOS, Windows (Python 3.x) and ubuntu Python 3.9	pipx comes from its own hash lock. The wheel is fetched from TestPyPI's file host by the recorded digest and checked against it. Every pip, pipx's included, uses PIP_INDEX_URL=https://pypi.org/simple/, so git-filter-repo comes from PyPI and never from TestPyPI. git-filter-repo must be absent before the install. pipx must place exactly the five commands, openRepoShape with its capitals (.exe on Windows), and that is the openRepoShape on PATH. --version must name the version, tag, commit and digest. --preflight must run. --doctor over an empty repository must exit 2, and its machine row must find git-filter-repo in the pipx environment. git filter-repo --version must work on the PATH from the package's own standard.child_environment (on Windows this is git for Windows finding git-filter-repo.exe). The four tools must answer --help. On Windows, PowerShell must run openRepoShape --version.
pypi	v* tag only, after testpypi and every install leg	Environment pypi, which waits for Brett Heap's approval; id-token: write. The same pre-upload checks as testpypi, then the upload. Afterwards PyPI must serve exactly the verified digest.

A dispatch on a branch is the rehearsal. It runs build in full and every install leg over the build's own wheel. Both upload jobs are skipped by their if:, and both environments' v* limit refuses any copy of the file a branch carries. The workflow's header comment says so, and also carries a short RELEASING TO PyPI section for the docs PR to reference, because no docs/release-notes/v1.1.0.md exists yet.

Also in this PR:

• .github/release-build-requirements.txt: a hash lock for build and hatchling==1.27.0, with hatchling's own requirements packaging, pathspec, pluggy, trove-classifiers and tomli (below 3.11). It is universal for Python 3.9 and later and resolved by uv 0.12.18 from PyPI as of 2026-10-01; the header holds the regeneration command.
• .github/release-pipx-requirements.txt: the same for pipx: 1.11.1 below Python 3.10, 1.17.8 above.
• pyproject.toml: a paragraph under the backend pin saying the release is where the wheel is shown reproducible, and what the pin alone leaves resolved on the day of a build. It is a comment only, and it keeps The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590's own wording above it.
• .github/workflows/tests.yml: its actionlint step reads release.yml too.
• tests/test_release_workflow.py: offline. It reads release.yml with repo_shape.load_yaml, and it runs three of its steps' own scripts: the stamp, the wheel check, and the main-or-release-branch check.

Why

#563 decision 5: TestPyPI, then an install check on three systems, then PyPI, in one dispatched run with each upload held for approval. Also review RV590's SHOULD 6, which the release build now meets:

• the reproducibility check is two git archive extractions in two directories, not two builds in one checkout;
• hatchling's own requirements are hash-locked.

Tests

• tests/test_release_workflow.py: 56 passed after fix round 3 (54 after round 2, 44 after round 1, 21 at first). Every assertion was checked against a mutated release.yml. In the first round each of these failed exactly one test: id-token added to install, the publish action pinned by tag, a push trigger, --require-hashes dropped, a job dropped from the gate, the gate step deleted, the tag check deleted, the wrong environment, and pypi without its if:. RV599's own mutations are covered under the review sections below.
• With tests/test_repo_hygiene.py, tests/test_openreposhape_package.py and the tests/test_install_sh.py test that reads tests.yml: 192 passed, on base d090f0c5 (/usr/bin/python3 -m pytest, stub gh, GH_TOKEN=bogus).
• actionlint 1.7.12 (the tarball tests.yml pins, sha256-checked), over the four files tests.yml now hands it: 0 findings. shellcheck was on PATH, and actionlint ran it.
• A local rehearsal of the workflow's own run: scripts, each pulled from release.yml and run under bash -eo pipefail with GitHub-style env files. gh was shimmed to read-only gh api.
  • Refusals. The version step refuses 1.1, 01.1.0, 1.1.0rc1, 0.0.0, 1.1.0.post1, a leading space and an embedded newline. The tag step passes the real annotated v1.0.1 at 8cda1397. It refuses the wrong tag, the right tag at another commit, a missing tag, and a pull ref; a branch is a rehearsal.
  • Live forge. Both environments are refused here: neither exists yet. They pass against openDox-code's real environments. The approval check passes on openDox-code's approved run 37339111713. The gate refuses 8cda1397 (v1.0.1's commit: no tests.yml run ever ran on it) and d53080ae (The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590's earlier head, tested only by a pull_request run); re-checked under the round-2 gate. The digest step agrees with the forge on d53080ae.
  • The build. On d090f0c5 plus this PR's files (a scratch commit, never pushed), two builds from the two extractions are one file (sha256 904d1343…), and the wheel check passes. The wheel check refuses a changed module, a changed stamp line, an extra file, a changed Requires-Dist and a missing module. build --no-isolation exits 1 when the backend does not satisfy [build-system] requires.
  • The install check. Its steps pass on Linux with Python 3.12 (pipx 1.17.8) and Python 3.9.25 (pipx 1.11.1), both installed from the lock with hashes. The TestPyPI fetch was checked with a curl shim, and it refuses a file host other than TestPyPI's. The index checks were run against live PyPI JSON and a local fake index: no file, another file held, served, yanked.
• Not run anywhere yet: the macOS and Windows legs (including the PowerShell step), the artifact and publish actions, and trusted publishing. Those need a real dispatch, and the first is the rehearsal on a branch after Brett Heap's acts.

Review (RV599) and fix round

RV599 found one MUST, five SHOULDs and two nits. All are fixed at 9a632c46.

• MUST 1: the gate counted runs that never tested the release commit's own tree. A pull_request run reports the PR head but tests a merge, and a check run created with an Actions token can land in tests.yml's check suite. The gate now reads the jobs of tests.yml runs whose head_sha is the commit and whose event is push or workflow_dispatch (RV599's code), and checks: read is gone. Read-only against live data:
  • 006caf42, unmerged adopt-project.py: check recomputes each pin's digest at the plan's commit in the clone plan read it from, where that clone is still on the machine and is no partial clone, so a commit or a digest edited into the plan no longer checks ok and reaches the root as adoption verified over a red validate-pins.py (#449) #589's head: exit 1 (only a pull_request run tested it);
  • bfed143e: exit 0 (a dispatch run, every job green);
  • 26c16009: exit 1 (main's push run, tests alone; it passes since round 2, which requires tests alone).
• SHOULD 1: the header. Each trusted publisher's environment is marked REQUIRED, with the reason: with none, a branch's own copy of the file could drop environment: and still publish. A ruleset on v* tags is recommended. openDox-code's accepted limits are carried over: anyone who can push a v* tag runs that tag's own copy of the file, the approval is the last line, and lane sessions act as brettheap.
• SHOULD 2: the commit is on main or the version's release branch. A new step after the tag step requires compare/<sha>...refs/heads/<branch> to answer identical or ahead for main or release/v${VERSION%.*}; a branch rehearsal skips it. Live: v1.0.1's 8cda1397 passes on release/v1.0, fb786c11 passes on main, and The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590's d090f0c5 refuses.
• SHOULD 3: tests that catch the surviving mutations. New tests check the intended if:s only, no continue-on-error, persist-credentials: false on both checkouts, no PIP_* beyond the install check's two, each upload job's fixed step order with the same scripts in both jobs and exact publish inputs, the wheel check's position and comparisons, and bare success exits only on the rehearsal and the two 404 paths. All 20 of RV599's mutations, plus three on the new gate, now fail a test. One RV599 pattern occurs in both upload jobs, so it was applied to TestPyPI's copy.
• SHOULD 4: tests.yml's actionlint step reads release.yml, and a test asserts it.
• SHOULD 5: the wheel check refuses unless entry_points.sections() == ["console_scripts"] and .dist-info/ is exactly its five files. The check now runs as a test over a wheel made from HEAD's own blobs, and it passes the real hatchling wheel from the rehearsal.
• Nits: pyproject.toml now says "path-independent", and the header no longer calls a second build "a second set of bytes".

Review (RV599) round 2 and fix round

RV599's second pass found every round-1 item fixed and its numbers reproduced, and one new MUST and one new SHOULD. Both are fixed at d2fdc6b7.

• MUST 2: the gate required jobs that no longer exist. Since ci: run the test suite on Linux only #597 (654c476c), tests.yml runs tests on every trigger and no longer has the macOS and Windows jobs, so a gate asking for tests-macos and tests-windows refused every commit, 654c476c included. The gate now names ("tests",). It still never takes the set from what a run holds, so a job gone missing is a refusal. The step is "the commit carries a passing tests job", its refusal says to dispatch tests.yml at the commit, and the header's step 1 says main's push run passes tests while a release/v<X.Y> branch needs a dispatch. Read-only on live data:
  • 654c476c: exit 0 (its push run);
  • 006caf42: exit 1 (a pull_request run alone);
  • bfed143e and 26c16009: exit 0.
• SHOULD 6: no test ran the gate's decision. The gate's own script now runs under a fake gh that answers the commit's runs and each run's jobs, in ten cases:
  • a push or a dispatch run with tests green passes;
  • a pull_request run alone, a run of another head or another workflow, a skipped job, and a run with no tests job are refused as not run;
  • a job still in progress refuses as in progress;
  • an older success followed by a newer failure refuses, and an older failure followed by a newer success passes;
  • only the counted runs' jobs are read.
• Mutations. RV599's two survivors, running = [] and max made min, now fail that test. All 24 applicable mutations are caught: mut2.py's list read as data, three on the gate's filters, and the two survivors. The one skipped mutation targets the check-run filter that MUST 1 removed.
• Checks. The 190-test set passes; actionlint 1.7.12 and pyflakes are clean.
• Not in this round, as instructed: no merge of l3-563-pypi-package or main (The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590 takes in ci: run the test suite on Linux only #597 first), and the install check's matrix is unchanged.

Review (RV599) round 3 and fix round

RV599's third pass called #599 READY at d2fdc6b7: MUST 2 and SHOULD 6 were confirmed, and all 14 of its new mutations failed a test. One SHOULD and one nit were left. Both are fixed at b0182e23.

• SHOULD 7: the release steps named no remedy for a cancelled push run. 11 of the last 20 tests.yml push runs on main were cancelled by the next landing, so main's 2bf8fd4c is refused with "ended cancelled". The header's step 1 now says main's push run counts only when it finished green, and gives the remedy:

  • before tagging, dispatch tests.yml on a branch that points at the release commit (a release/v<X.Y> branch serves while it is still at that commit), and wait for it;
  • --ref main tests main's CURRENT head, not an older commit;
  • if the tag is already pushed and the gate refused it, dispatch on the tag (gh workflow run tests.yml --ref v<version>), wait, and re-run the release run.

  The branch route leads, because a tag dispatch running at the tag's commit is GitHub's documented behaviour but not yet seen here. The "has not run" and "ended " refusals name the same commands. Live: 2bf8fd4c still refuses, now naming them; 654c476c passes, and 006caf42 refuses with the remedy.

• Tests and mutations. Two gate cases are new: a cancelled push run refuses, and a dispatch after it passes. Each refusal must name the three remedy pieces. All 26 applicable mutations are caught, including two that drop the remedy from either refusal; the one skipped mutation targets the check-run filter MUST 1 removed.

• Nit: release.yml, the test's GATE comment and this body now say tests.yml "runs tests on every trigger", not that it holds one job: The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590's package job stays.

• Checks. The verify set gives 192 passed (the 190 set plus the two new cases), with basetemp w563b-r3-bt; actionlint 1.7.12 and pyflakes are clean. There was no merge of l3-563-pypi-package, and the install check's legs are unchanged.

Merge of #590's 70955e4

750366bc merges #590 at 70955e4d. That head brings in its merge of main (#596's tests-git-bash job, #593's concurrency group, #597's Linux-only tests job), lane 5's bash_path hunks and a header-comment fix.

• No conflict. Git merged .github/workflows/tests.yml by itself. The result is The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590's file whole (jobs tests, tests-git-bash and package, and its header wording) plus only The release workflow: a dispatch on the annotated tag v<version> builds the openreposhape wheel twice from git archive of a commit whose own tree passed the tests job, uploads it to TestPyPI, installs it with pipx on three systems and Python 3.9, and uploads the same bytes to PyPI on approval (#563) #599's change: .github/workflows/release.yml in the actionlint step, with its comment and step name. Every other path is The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590's, plus The release workflow: a dispatch on the annotated tag v<version> builds the openreposhape wheel twice from git archive of a commit whose own tree passed the tests job, uploads it to TestPyPI, installs it with pipx on three systems and Python 3.9, and uploads the same bytes to PyPI on approval (#563) #599's own files and its pyproject.toml paragraph.
• The release gate stays ("tests",). tests-git-bash is a small extra job, not a release gate. test_tests_yml_lints_the_release_workflow and the gate tests that read tests.yml pass.
• Checks. These ran under the stub-gh rules with basetemp w563b-r4-bt:
  • test_release_workflow.py, test_repo_hygiene.py, test_openreposhape_package.py, test_workflow_concurrency.py and test_install_sh.py::test_it_installs_the_git_filter_repo_ci_runs: 197 passed;
  • actionlint 1.7.12 over the four files tests.yml lints: 0 findings.

Merge of main after #590's squash

eaa0cda1 merges main at fe237ec7 into 750366bc. fe237ec7 is #590's squash of 70955e4d, plus #626. This PR now targets main.

• The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590's files are unchanged on main. git diff --stat 70955e4d fe237ec7 lists only family.py: add, bump and remove refuse before their first write a merge, cherry-pick, revert, rebase or git am in progress, a .gitmodules, members/ or family.yaml the sparse checkout leaves out, and a file named members, which each failed after writing and was rolled back, or committed in the wrong place (#612) #626's two files, scripts/family.py and tests/test_family_refuse_up_front.py. That is the same diffstat as family.py: add, bump and remove refuse before their first write a merge, cherry-pick, revert, rebase or git am in progress, a .gitmodules, members/ or family.yaml the sparse checkout leaves out, and a file named members, which each failed after writing and was rolled back, or committed in the wrong place (#612) #626's own commit 6f760b7. So every file The openreposhape package: openRepoShape and four tool commands, run from a clone of the standard at the stamped commit and checked against its digest; --install and install.sh refuse a symlinked target (#563) #590 touched has the same blob on main as at 70955e4d.
• One conflict: add/add on pyproject.toml. Main's blob 7e1a364b equals 70955e4d's. This branch's blob 4791b545 is that blob plus this PR's 11-line paragraph, with no line removed. The resolution keeps this branch's side.
• .github/workflows/tests.yml merged by itself to eac56645. That is main's blob 7928afaf, which equals 70955e4d's, plus only this PR's actionlint lines.
• family.py: add, bump and remove refuse before their first write a merge, cherry-pick, revert, rebase or git am in progress, a .gitmodules, members/ or family.yaml the sparse checkout leaves out, and a file named members, which each failed after writing and was rolled back, or committed in the wrong place (#612) #626 merged cleanly. scripts/family.py came out as main's blob 709e8a92.
• Against main. git merge-tree --write-tree fe237ec7 eaa0cda1 is clean and writes a0147411, which is HEAD's own tree. git diff fe237ec7 eaa0cda1 touches six files, all this PR's own:
  • .github/workflows/release.yml;
  • the two hash locks, .github/release-build-requirements.txt and .github/release-pipx-requirements.txt;
  • tests/test_release_workflow.py;
  • tests.yml's actionlint lines (7 lines);
  • pyproject.toml's paragraph.
• Main has moved since. f1c73e2 (the workflow-unreadable refusal in validate-pins.py) touches two files this PR does not. git merge-tree --write-tree f1c73e2 eaa0cda1 is clean, and its diff against f1c73e2 is the same six files.
• Checks. These ran under the stub-gh rules with basetemp w563b-r5-bt:
  • the same five targets as round 4 gave 197 passed: test_release_workflow.py 56, test_workflow_concurrency.py 5, test_repo_hygiene.py and test_openreposhape_package.py 135, and the CI-pin test 1;
  • actionlint 1.7.12 over the four files tests.yml lints: 0 findings.

#590 has landed as fe237ec7. Nothing is uploaded until Brett Heap creates the trusted publishers on pypi.org and test.pypi.org and the testpypi and pypi environments.

Refs #563

🤖 Generated with Claude Code

Summary by Sourcery

Establish a gated, reproducible release pipeline that verifies and promotes one wheel from an annotated release tag through TestPyPI to PyPI.

New Features:

• Add a dispatch-only release workflow that builds and verifies a reproducible wheel, publishes it to TestPyPI, validates installation across Linux, macOS, Windows, and Python 3.9, and publishes the same artifact to PyPI after approval.

Enhancements:

• Enforce release provenance, passing commit-specific tests, repository tree integrity, locked build tools, artifact digests, package contents, and protected publishing environments.
• Add offline workflow tests covering release safeguards, build verification, installation requirements, and mutation resistance.

Build:

• Add hash-locked requirements for release builds and pipx installation checks.

CI:

• Run actionlint against the release workflow as part of the regular test workflow.

Deployment:

• Use GitHub OIDC trusted publishing with required environment approvals and tag restrictions for TestPyPI and PyPI.

Documentation:

• Document the release prerequisites and procedure in the release workflow and clarify reproducible release dependency resolution in pyproject.toml.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 15 hours by commenting @sourcery-ai review. Upgrade to get a review now.