PyPI trusted publishing is unconfigured, and this is the one release workflow with no dry_run to rehearse it

[dmccoystephenson]

What is missing

release-pypi.yml publishes by PyPI trusted publishing (OIDC), which needs configuration on PyPI's side that does not exist yet. The workflow has never been dispatched, so this is recorded from the workflow and repository state rather than from a failed run.

Two facts verified 2026-09-06:

• The pypi environment does not exist. gh api repos/kingdom-community/github-docs/environments returns total_count: 0. The publish job declares environment: pypi at line 15. The npm workflow declares environment: npm at its line 20, and that does not exist either.
• The project does not exist on PyPI. https://pypi.org/pypi/github-docs/json returns HTTP 404.

The workflow says so itself at lines 27-28:

Trusted publishing: configure this repo + workflow as a publisher on PyPI, and no long-lived API token has to exist anywhere.

Why the ordering matters

Because github-docs has never been published, the binding must be created as a pending publisher — PyPI's flow for a project that does not exist yet, which converts to a normal publisher on the first successful upload. A publisher cannot be attached to a project that is not there.

Every value must match exactly or the OIDC exchange is refused:

Field	Value
PyPI project name	github-docs
Owner	kingdom-community
Repository	github-docs
Workflow filename	release-pypi.yml
Environment	pypi

The pypi environment must then be created in this repository, and npm alongside it for release-npm.yml.

The first dispatch here is irreversible, and there is no rehearsal

This is the one release workflow in the set with no dry_run input. session-client's two workflows both default dry_run to true, so a first dispatch there builds, tests and checks the distributions without uploading anything. This workflow has no such setting: the moment the publisher is configured, the next dispatch uploads for real.

That matters more on PyPI than on npm. A PyPI version number can never be reused — a 0.1.0 uploaded by mistake cannot be replaced, only yanked, and 0.1.1 becomes the first usable version. Adding a dry_run input matching the pattern already used in session-client would make the first run rehearsable, and is proposed as a prerequisite rather than a nice-to-have.

A name worth checking before it is claimed

github-docs is an extremely generic distribution name on a shared public namespace, and it reads as though it belongs to GitHub rather than to this project. It is unclaimed today. Whether the distribution ships under github-docs or under a name scoped to this project should be settled before the pending publisher is created, because the publisher binds to the name.

This connects to the open question already raised in #5: the Python half has no consumer anywhere in the fleet today, so whether it ships at all in 0.1.0 is undecided.

What is being proposed

• Add a dry_run input to release-pypi.yml, defaulting to true, matching session-client's pattern — so the first run can be rehearsed.
• Decide whether the Python distribution ships now, and under what name, per the open question in 0.1.0 is unpublished on npm and PyPI, so 505 lines of forked GitHub-content code stay duplicated across two orgs #5.
• Create the pending publisher on PyPI with the five values above; create the pypi and npm environments in this repository.
• Dispatch with dry_run: false only once the rehearsal has passed.
• The npm half is additionally blocked on a missing organisation secret, tracked in kingdom-community/.github#2.

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

The first prerequisite listed here has since been satisfied.

Add a dry_run input to release-pypi.yml, defaulting to true, matching session-client's pattern — so the first run can be rehearsed.

That landed in #7 (9f47060). release-pypi.yml now takes a dry_run input, the build-and-check job is gated on it at line 45, and the publish job is gated on its negation at line 54. The comment at line 5 records that the default is a rehearsal. release-npm.yml received the same treatment in the same PR, so the asymmetry that made this workflow the odd one out is gone.

What remains here is unchanged and is not something a change to this repository can settle:

• The pending publisher on PyPI, bound to the five values tabulated above.
• The pypi and npm environments in this repository.
• The decision about the distribution name, which binds at publisher-creation time and is entangled with the open question in 0.1.0 is unpublished on npm and PyPI, so 505 lines of forked GitHub-content code stay duplicated across two orgs #5 about whether the Python half ships in 0.1.0 at all.

This issue was reviewed during a development cycle and deferred for that reason — every remaining step is an operator action on a system outside this repository, so it is not work a code change can close. It is recorded here rather than left silent so the deferral reads as a classification and not as a judgement about priority.

---

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson