#58 ci(release): pin publish job to a named environment and tag refs

User description

What this changes

One job in .github/workflows/release.yml — publish, the only job in the pipeline that mints a short-lived OIDC identity and hands it to a package registry. Two lines of behaviour, no change to what gets built, tested, or uploaded.

1. A ref floor on the credential-minting job. The publish job now carries an if: guard and runs only when one of three things is true: the run is a v* tag push, the run is a published release, or the run is a workflow_dispatch from the default branch. Anything else — a dispatch from a feature branch, a fork branch, a scratch branch — stops at this job instead of requesting the environment and reaching the registry.

2. A comment making the existing environment and permission scoping non-accidental. The named environment and the job-scoped id-token: write were already correct here; they are now documented as load-bearing so a future edit does not hoist the mint to the workflow level or drop the environment name that the registry-side publisher configuration is pinned to.

Why the ref guard is not redundant with the checks already here

The resolve-ref job already does real work: it validates the tag against a full-anchored v<semver> regex, proves the tag resolves to a real commit object, and requires that commit to be an ancestor of origin/main. That chain guarantees the code this pipeline publishes was merged and reviewed on the default branch. It deliberately says nothing about the run's own ref.

That distinction matters, because the run's ref is not inert. It is the value that lands in the ref claim of the OIDC token the runner mints, and it is what scopes the run's Actions cache. A workflow_dispatch triggered from an arbitrary branch would previously have satisfied every existing check — the tag it names is still ancestry-verified — while minting a publishing credential under that branch's identity and running inside that branch's cache scope. The guard closes exactly that gap and nothing else.

Why the third clause exists

A strict refs/tags/v*-only guard would have been simpler and wrong. This workflow has a deliberate, documented idempotent-backfill path: an operator dispatches it from the default branch naming an already-shipped tag, and the pipeline re-runs without re-publishing (the registry-version check already no-ops the upload for a version that exists). Dropping that path to satisfy a tidier condition would have traded a working operational capability for a cosmetic one. The default-branch clause keeps the backfill and still excludes every other branch; the ancestry check continues to anchor which tree that dispatch may act on.

The clause is also written to fail closed: format('refs/heads/{0}', github.event.repository.default_branch) yields refs/heads/ if the payload ever lacks default_branch, and that matches no real ref — so an unexpected event shape denies the publish rather than admitting it.

Verification

Actions runs are not currently executing on this organisation, so this was verified locally rather than by a green check on this PR:

• actionlint .github/workflows/release.yml — exit 0, no findings.
• The workflow parses as YAML and the resulting job graph is unchanged: resolve-ref, verify, publish, sbom, release.
• Parsed publish job asserts, post-change: environment = pypi, permissions = {id-token: write, contents: read}, workflow-level permissions = {contents: read}.
• Diff is additive only: 21 lines, one file, no deletions.

Operator follow-up, not in this PR

This PR changes workflow files only. Naming an environment does not create it or protect it — that is repository configuration and is left entirely to a maintainer. Until the environment exists with a required reviewer and a tag-scoped deployment policy, and until the registry-side publisher is pinned to the same environment name, the if: guard above is the active control and the environment name is a declaration awaiting its other half.

🤖 Generated with Claude Code

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[!NOTE]
Medium Risk
Changes release pipeline authorization for PyPI OIDC publishing; misconfigured conditions could block legitimate backfills or leave a gap if expressions are wrong, though the intent is fail-closed.

Overview
Tightens who can mint PyPI publishing credentials in the release workflow by adding a job-level if: on publish. That job now runs only for v* tag pushes, published GitHub releases, or workflow_dispatch from the default branch—blocking dispatches from feature or fork branches that could still pass tag ancestry checks while putting the run’s OIDC ref and Actions cache under an untrusted branch identity.

The diff is otherwise comment-only documentation around the existing pypi environment and job-scoped id-token: write, so future edits don’t hoist OIDC minting to workflow scope or drop the environment name PyPI Trusted Publishing expects.

^{Reviewed by Cursor Bugbot for commit 994714040bcec5a31ddbcbf40069000613d581ae. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by Sourcery

Harden the release workflow by limiting publishing credentials to approved refs while preserving the default-branch backfill path.

Enhancements:

• Restrict the PyPI publishing job to tag pushes, published releases, and default-branch manual dispatches.
• Document the publish job’s named environment and job-scoped OIDC permissions as required security boundaries.

CI:

• Add a fail-closed ref guard to prevent publishing credentials from being minted for arbitrary branches.

CodeAnt-AI Description

Restrict PyPI publishing to approved release refs and environment controls

What Changed

• PyPI publishing now runs only for version tag pushes, published releases, or manual runs from the default branch
• Publishing is tied to the pypi environment so its configured protection rules and registry trust settings can gate credential issuance
• The publishing credential remains limited to the publish job instead of being available to the whole workflow

Impact

✅ Fewer accidental PyPI publications
✅ Release credentials limited to approved refs
✅ Environment review gates protected publishing

@codeant-ai ask: Your question here

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

@codeant-ai: Your feedback here

@codeant-ai: Do not flag unused imports.

@codeant-ai: review