Release to PyPI¶
Release on merge replaces the tag and approval stages
Since 0.15.2, every merge to main is a release. publish.yml computes
the version, tags it and publishes it, with no approval
(changelog.d/README.md).
Another repository calls the same workflow,
zeroemployeeorg/zeocore/.github/workflows/release-on-merge.yml@<sha>,
and keeps its own top-level PyPI job, because trusted publishing can't run
inside a reusable workflow. The plan, admit, apply and approve
stages below describe the earlier tag-and-approve path. reconcile and
verify still check a published release, from a local manifest that
names its version and commit.
zeocore release pypi is the PyPI adapter (ZEOCORE-SOW-26). It changes
nothing about how a package publishes: the repository's publish.yml builds
and publishes through trusted publishing when a vX.Y.Z tag is pushed,
behind its pypi environment's approval. The adapter makes every step around
that approval explicit, receipted and reconcilable.
Two identities, delegated by the operator¶
The operator delegated releases on 2026-10-11:
- the
zeo-releaseGitHub App creates thev*tag. Its private key is in the signing host's Keychain aszeo-release-app-key, and it is read only to sign the App's own short-lived JWT. Each tag is made with a fresh installation token for that one repository, withcontents: write, which is revoked as soon as the call is answered; - matorclawson approves the
pypideployment, as its only required reviewer.
Neither identity can release alone. Configure the App's numeric id (not a
secret) with ZEOCORE_RELEASE_APP_ID; set
ZEOCORE_RELEASE_APP_KEY_ACCOUNT if the Keychain item's account isn't
private-key.
The targets¶
Each target is a row in zeocore's reviewed table
(zeo_core.release.pypi.targets.TARGETS): zeocore, zeocreator and
sovereign-agent. Each row gives the repository, the workflow and the
environment. A manifest can name only a row in that table. zero-employee is
not a PyPI target: it is now zeoruntime, released Go-only through the shared
signed release component (the operator, 2026-10-12).
The manifest¶
Each target's release.yaml, changed in the release's own reviewed PR. A
file can't name the commit it's part of, so the committed section has no
commit:
pypi:
project: zeocore
version: X.Y.Z
repository: zeroemployeeorg/zeocore
workflow: publish.yml
environment: pypi
The stages read a local copy of that section, with commit added: the
40-hex commit on the default branch that the release is cut from. plan
refuses unless every other field equals release.yaml at that commit
(manifest_unreviewed).
The stages¶
| Stage | Effect | Answers |
|---|---|---|
plan |
none | planned, with the tag it would create, once the commit is on the default branch, the target's workflow file is at that commit (workflow_missing otherwise: a v* tag can't be deleted under the ruleset, so it is never made with nothing to publish it), pyproject.toml, release.yaml and CHANGELOG.md name the version, PyPI hasn't got it, and the tag is absent or already at the commit |
admit |
none | admitted only when the two identities, together, are the only way to release (below) |
apply |
one: creates the tag vX.Y.Z, as the App |
tag_created, or already_applied |
approve |
one: approves the waiting pypi deployment, as matorclawson, once |
approved, or already_approved |
reconcile |
none | the tag, then its run: awaiting_approval (exit 11), publish_failed, or published |
verify |
none | publisher_recorded when PyPI lists a wheel and an sdist, neither yanked, and each file's attestation names the target's publisher and exactly that file and digest |
verify checks the publisher PyPI recorded for each attestation, not its
Sigstore signature, and says so in its answer.
What admit requires¶
Read through GitHub's own API; anything else is refused:
- matorclawson is the
pypienvironment's only required reviewer (promotion_unbound), with self-review prevented (self_review_allowed) and no admin bypass (admin_bypass_possible); - the environment deploys only from
v*tags (deployment_policy_unrestricted). Every page of the policy list is read, and a list read short of GitHub's count is unreadable; - an active ruleset on
refs/tags/v*, with no exclusions, restricts creation, update and deletion (tag_ruleset_missing), and matorclawson can't bypass it: its owncurrent_user_can_bypassisnever(approver_can_bypass); ghacts as matorclawson, the approver (approver_mismatch).
The ruleset's exact bypass list isn't checked. GitHub shows it only to a
repository Admin, and under ruling r7 no agent is one, so the operator chose to
check what is visible instead (SOW-29, option C). The residual risk is an unseen
bypass actor creating a v* tag, and that can't publish on its own: the run
still waits on matorclawson, and approve approves only a reviewed commit on
the default branch. The runbook already accepts that risk.
- the release App's id is configured (release_app_unconfigured).
apply and approve¶
Both journal in this user's $XDG_STATE_HOME/zeocore/release/pypi-journal.jsonl
(by default under ~/.local/state), keyed by repository and version. So one
release is tagged once and approved once, whatever the commit or directory.
applysettles an earlier attempt first, by reading the tag back, beforeplanoradmitcould hide it. It then runs both again, checks that the Keychain key signs forzeo-releaseitself (creator_not_release_app), writes its intent, and makes onePOST /git/refs. A lost answer isapply_unreconciled(exit 13), and is never retried.approveapproves only the one run of that exact tag and commit, waiting onpypialone, afterplanandadmitpass again. Anything else isapproval_unexpected. A run that has stopped waiting isrun_not_waiting, held, never a success. A lost answer isapprove_unreconciled, and is never sent again. It is settled only by reading GitHub's own record of the run's reviews: matorclawson's approval ofpypicloses it, and a rejection closes it asapproval_rejected.
The adapter never holds a PyPI credential and never dispatches a workflow.
GitHub reads go through gh, and PyPI is read anonymously from
https://pypi.org.