Problem or motivation
The current release workflow uses cycjimmy/semantic-release-action with conventional-commit title parsing. This approach has several problems:
- It commits back to
main after every release via @semantic-release/git and @semantic-release/changelog, requiring a PAT or elevated token to bypass branch protection.
- Versioning is tied to commit message conventions rather than explicit decisions, e.g. a typo in a commit prefix silently skips a bump or triggers the wrong one.
- Semantic-release configuration lives in
.releaserc.json per-repo with no shared source of truth, so behaviour drifts across the stack.
- PyPI publishing uses a stored secret token rather than keyless OIDC.
- There is no gate preventing a PR from merging without a deliberate version-bump decision.
A centralised solution was designed in AustralianCancerDataNetwork/cava-devops and validated end-to-end in AustralianCancerDataNetwork/cava-ci-test.
The new system provides:
- A
label-gate that blocks merges without exactly one of five bump labels: an explicit, reviewable bump decision on every PR
release-drafter accumulating changelog entries in GitHub Releases rather than committing CHANGELOG.md back to mainhatch-vcs deriving the version from git tags at build time: No static version string in any source file, no file write required- OIDC trusted publishing to PyPI: no stored token, no secret rotation
- All CI logic lives in one repo (
cava-devops) and propagates to all callers on their next run: no manual syncing of workflow files across the stack
Pitch
Replace the existing release workflow with the centralised reusable workflows from AustralianCancerDataNetwork/cava-devops. The per-repo change is minimal:
- three new workflow files,
- a
pyproject.toml switch to hatch-vcs, and
- deletion of the old release workflow and
.releaserc.json.
No behaviour change to the package itself.
Alternatives considered
1. GitHub App with cross-repo write access
The original plan was to use a GitHub App (or organisation-level PAT) to allow semantic-release to commit back to main and to automate template sync across repos. Rejected because it requires ongoing credential management, gives a machine account write access to all repos, and does not address the underlying coupling of versioning to commit message conventions.
2. uv-dynamic-versioning plugin
uv-dynamic-versioning would have derived versions from git tags within the uv ecosystem, keeping everything inside the uv toolchain already used throughout the build pipeline. Rejected because the plugin explicitly does not work with the uv build backend at this time (upstream issue astral-sh/uv#14561).
3. Keep semantic-release, add OIDC publish only
Would fix the stored-token problem but leave the commit-back pattern and per-repo config drift in place.
Problem or motivation
The current release workflow uses
cycjimmy/semantic-release-actionwith conventional-commit title parsing. This approach has several problems:mainafter every release via@semantic-release/gitand@semantic-release/changelog, requiring a PAT or elevated token to bypass branch protection..releaserc.jsonper-repo with no shared source of truth, so behaviour drifts across the stack.A centralised solution was designed in AustralianCancerDataNetwork/cava-devops and validated end-to-end in AustralianCancerDataNetwork/cava-ci-test.
The new system provides:
label-gatethat blocks merges without exactly one of five bump labels: an explicit, reviewable bump decision on every PRrelease-drafteraccumulating changelog entries in GitHub Releases rather than committingCHANGELOG.mdback tomainhatch-vcsderiving the version from git tags at build time: No static version string in any source file, no file write requiredcava-devops) and propagates to all callers on their next run: no manual syncing of workflow files across the stackPitch
Replace the existing release workflow with the centralised reusable workflows from AustralianCancerDataNetwork/cava-devops. The per-repo change is minimal:
pyproject.tomlswitch tohatch-vcs, and.releaserc.json.No behaviour change to the package itself.
Alternatives considered
1. GitHub App with cross-repo write access
The original plan was to use a GitHub App (or organisation-level PAT) to allow semantic-release to commit back to
mainand to automate template sync across repos. Rejected because it requires ongoing credential management, gives a machine account write access to all repos, and does not address the underlying coupling of versioning to commit message conventions.2.
uv-dynamic-versioningpluginuv-dynamic-versioningwould have derived versions from git tags within the uv ecosystem, keeping everything inside theuvtoolchain already used throughout the build pipeline. Rejected because the plugin explicitly does not work with theuv buildbackend at this time (upstream issue astral-sh/uv#14561).3. Keep semantic-release, add OIDC publish only
Would fix the stored-token problem but leave the commit-back pattern and per-repo config drift in place.