fix(ci): move PyPI publish out of a reusable workflow

PyPI does not accept a reusable workflow as a trusted publisher, at all --
pypi/warehouse#11096, unresolved. python-publish-to-pypi.yml is exactly
that shape: every consumer's release.yml and publish-dev-to-*.yml called
it via workflow_call, so every real publish attempt failed at the OIDC
exchange with invalid-publisher, regardless of what the trusted publisher
config named. Confirmed against four real release runs today, and against
a week of failing publish-dev-to-testpypi.yml runs across every
PyPI-publishing repo since the 2026-08-16 migration -- nobody had noticed.

actions/publish-to-pypi replaces it as a composite action. The OIDC claim
is about which workflow file the job runs in, not what its steps
reference, so a job defined directly in the caller's own workflow that
calls this action for steps still satisfies PyPI's requirement. Consumer
repos need a matching change to stop calling the old reusable workflow --
tracked as companion PRs.

python-publish-to-pypi.yml and its test are deleted rather than kept
around deprecated: leaving a known-broken-for-purpose reusable workflow in
place is exactly what invites someone to wire it up again.

Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>

Author: jimisola

.github/actions/publish-to-pypi/action.yml

@@ -0,0 +1,68 @@
+name: Publish to PyPI
+description: >
+  Upload a built distribution to PyPI or Test PyPI via trusted publishing (OIDC).
+
+# PyPI does not support trusted publishing through a workflow_call reusable
+# workflow -- https://github.com/pypi/warehouse/issues/11096, confirmed against
+# this org's own release runs on 2026-08-23. A composite action doesn't have
+# that problem: the OIDC claim is about which *workflow file* the job runs in,
+# and a job that calls a composite action for its steps still belongs to the
+# caller's own workflow file. So the upload step lives here, but the job that
+# calls this action -- with its `environment:` and `permissions: id-token:
+# write` -- must be defined directly in the caller's own workflow, never behind
+# `uses: reqstool/.github/.github/workflows/...@main`.
+#
+# This replaces python-publish-to-pypi.yml for that reason. That workflow is
+# kept only for tests/python/publish-to-pypi.yml's actionlint coverage; nothing
+# should call it for a real publish.
+
+inputs:
+  target:
+    description: "pypi (the real index) or testpypi."
+    required: false
+    default: "pypi"
+  dry-run:
+    description: "Run twine check instead of uploading."
+    required: false
+    default: "false"
+  artifact:
+    description: "Name of the build artifact holding the distributions."
+    required: false
+    default: "dist"
+
+runs:
+  using: composite
+  steps:
+    - name: Reject an unknown target
+      shell: bash
+      run: "$GITHUB_ACTION_PATH/check-target.sh '${{ inputs.target }}'"
+
+    - uses: actions/download-artifact@v8.0.1
+      with:
+        name: ${{ inputs.artifact }}
+        path: dist
+
+    - name: Dry-run — validate artifacts
+      if: ${{ inputs.dry-run == 'true' }}
+      shell: bash
+      run: |
+        # renovate: datasource=pypi depName=twine
+        pip install --quiet twine==7.0.0
+        twine check --strict dist/*
+
+    - name: Publish to Test PyPI
+      if: ${{ inputs.dry-run != 'true' && inputs.target == 'testpypi' }}
+      uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        attestations: true
+        # A re-run after a downstream failure must not fail on the upload that
+        # already succeeded. Not set for the real index, where a silent no-op
+        # would hide a version collision.
+        skip-existing: true
+
+    - name: Publish to PyPI
+      if: ${{ inputs.dry-run != 'true' && inputs.target == 'pypi' }}
+      uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+      with:
+        attestations: true

.github/actions/publish-to-pypi/check-target.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+#
+# Fail unless $1 is 'pypi' or 'testpypi'.
+#
+#   check-target.sh pypi
+#
+# Kept as a script rather than inline in action.yml so tests/actions/ can run it
+# directly -- see check-version.sh for why.
+
+set -euo pipefail
+
+TARGET="${1:?usage: check-target.sh <pypi|testpypi>}"
+
+case "$TARGET" in
+  pypi|testpypi) ;;
+  *)
+    echo "::error::target must be 'pypi' or 'testpypi' (got: '$TARGET')"
+    exit 1
+    ;;
+esac

.github/workflows/python-publish-to-pypi.yml

@@ -124,6 +124,16 @@ cleaner option, as below.
 > pypi.org (project → Publishing) must read `stable`, and on test.pypi.org `test`. The same
 > applies to any other registry that binds an OIDC identity to an environment name.
 
+> **PyPI does not accept a reusable workflow as the trusted publisher at all**, not even with
+> the right names —
+> [pypi/warehouse#11096](https://github.com/pypi/warehouse/issues/11096), unresolved as of
+> this writing, confirmed against this org's own release runs on 2026-08-23. The job that
+> calls `pypa/gh-action-pypi-publish` must be defined directly in the caller's own workflow
+> file; `actions/publish-to-pypi` is a composite action, not a `workflow_call` workflow, for
+> exactly this reason — a job that uses it for steps still belongs to the caller's own
+> workflow for OIDC purposes. Every PyPI-publishing repo's `release.yml` and any
+> `publish-dev-to-*.yml` must call it this way, never through another reusable workflow.
+
 ## Cutting a release candidate
 
 Set `prerelease` to `rc` (or `b`/`a`) and run the workflow as normal. It does everything a
@@ -185,7 +195,8 @@ prepare  (dry-run stops here)
   → [approval] tag        common-release-tag.yml
   → build @ tag           the repo's own build.yml, ref = the tag
   → assets                common-release-assets.yml
-  → publish               python-publish-to-pypi.yml / java-publish-to-maven.yml / …
+  → publish               actions/publish-to-pypi (job in the caller's own workflow)
+                          / java-publish-to-maven.yml / …
   → promote               common-release-promote.yml
 ```
 

RELEASING.md

@@ -134,6 +134,16 @@ expect 1 "an unknown format is rejected"                -- "$NP" 0.5.0 rc npm
 
 cd "$ROOT" || exit 1
 
+# --------------------------------------------------------------------------
+# publish-to-pypi/check-target.sh
+# --------------------------------------------------------------------------
+CT="$ACTIONS/publish-to-pypi/check-target.sh"
+
+expect 0 "pypi is accepted"              -- "$CT" pypi
+expect 0 "testpypi is accepted"          -- "$CT" testpypi
+expect 1 "an unknown target is rejected" -- "$CT" prod
+expect 1 "an empty target is rejected"   -- "$CT" ""
+
 # --------------------------------------------------------------------------
 echo ""
 echo "$pass passed, $fail failed"