fix(ci): make a failed publish retryable, and unpin the stale twine (#63)

* fix(ci): make a failed publish retryable, and unpin the stale twine

v0.11.0 was tagged and its GitHub Release created, but the PyPI upload failed:

    Checking dist/hotdata_framework-0.11.0-py3-none-any.whl:
    ERROR InvalidDistribution: Invalid distribution metadata:
          '2.5' is not a valid metadata version

Nothing to do with the code. gh-action-pypi-publish was pinned at v1.13.0
(Sept 2025), whose bundled twine predates `Metadata-Version: 2.5`, which current
hatchling emits. Bumped to v1.14.2.

Note the build job's own `twine check --strict` PASSED, because it
pip-installs a current twine. So the incompatibility was invisible until upload,
by which point the tag was already public -- the check that exists to catch bad
metadata cannot catch this class at all.

RETRYABILITY IS THE REAL FIX. Both workflows triggered only on tag push, so a
publish that failed for reasons unrelated to the code left two bad options:
delete and re-push the tag, or burn a version number on a CI fix. Neither is a
reasonable answer to "the upload failed, run it again". Both now accept a
workflow_dispatch with a tag input, checkout that ref, and derive the version
from it.

release.yml gets the same treatment for a second reason: RELEASING.md already
documents the recovery command

    gh workflow run "GitHub Release" --ref main -f tag=vX.Y.Z

and the trigger it needs was never there, so that documented path has always
failed. This makes the doc true.

Verified both files parse with triggers ['push', 'workflow_dispatch'] and a
`tag` input, and no GITHUB_REF_NAME references remain in either.

* fix(ci): watch action pins, and stop dispatch from demoting a newer release

Three review findings, all confirmed before acting.

Dependabot had no github-actions ecosystem at all -- only a uv entry narrowed to
one dependency -- which is how gh-action-pypi-publish sat at v1.13.0 until its
bundled twine broke a release at upload. Added, with no allow filter, since the
point is to see every stale pin rather than a chosen one. Fixes the class, not
just the instance.

make_latest was unconditional. On the push trigger the tag is always the newest
version so that is right, but a dispatch repairs a Release for a tag that
already exists, by which time a newer version may have shipped -- re-running for
an older tag would silently demote the newer one and point /releases/latest at
it. Now gated on the push event.

And my comment cited a RELEASING.md recovery section that is not in this repo.
It is in sdk-python's RELEASING.md; I read that one earlier and attributed it
here. So the trigger was adding a capability documented nowhere, not making a
doc true. Added the section for real, including the bit worth stating outright:
--ref main selects the workflow definition while the tag input selects what gets
built, which reads like a contradiction until you know they differ on purpose.

* fix(ci): make_latest legacy, not a gate on the event

The gate was backwards for the case the dispatch will mostly see. make_latest is
not "set latest / leave alone" -- false is an explicit instruction that a release
is NOT the latest. release.yml's dispatch exists to repair a Release that failed
on the push run, where the tag IS the newest version, so gating on the event
passed false exactly there and left /releases/latest on the previous version.

legacy covers both directions without the workflow having to know which case it
is in: GitHub picks by tag date and semver, so repairing the newest tag marks it
latest and repairing an older one leaves the newer release alone.

* docs(releasing): scope what --ref main actually picks up

"any fix landed since the tag" was too broad. Both workflows check out
ref: ${{ inputs.tag || github.ref_name }}, so only the workflow YAML comes from
main -- everything it runs comes from the tag, including
scripts/extract-changelog.py. That is the right design, but the loose wording
invites the opposite conclusion for the exact failure this section covers: if
that script is what broke, a dispatch re-run does not pick up its fix.

Author: anoop-narang

.github/dependabot.yml

@@ -6,3 +6,12 @@ updates:
       interval: daily
     allow:
       - dependency-name: hotdata
+
+  # Action pins had no watcher, which is how gh-action-pypi-publish sat at
+  # v1.13.0 until its bundled twine broke a release at upload time. Unlike the
+  # uv entry there is no `allow` filter: the point is to see every stale pin,
+  # not a chosen one.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/publish.yml

@@ -4,9 +4,20 @@ on:
   push:
     tags:
       - 'v[0-9]*'
+  # Retry an existing tag without moving it. A publish can fail for reasons that
+  # have nothing to do with the code — a stale action pin, a PyPI outage — and
+  # with only the tag trigger the choices were to delete and re-push the tag or
+  # to burn a version number on a CI fix. Neither is a good answer to
+  # "the upload failed, run it again".
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing tag to build and publish (e.g. v1.2.3)
+        required: true
+        type: string
 
 concurrency:
-  group: pypi-publish-${{ github.ref_name }}
+  group: pypi-publish-${{ inputs.tag || github.ref_name }}
   cancel-in-progress: false
 
 permissions:
@@ -16,8 +27,13 @@ jobs:
   build:
     name: Build distribution
     runs-on: ubuntu-latest
+    env:
+      # The tag being released, whether it arrived by push or by dispatch.
+      TAG: ${{ inputs.tag || github.ref_name }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
@@ -28,11 +44,11 @@ jobs:
 
       - name: Verify tag matches pyproject version
         run: |
-          if [[ ! "$GITHUB_REF_NAME" =~ ^v[0-9] ]]; then
-            echo "Release tag '$GITHUB_REF_NAME' must start with 'v' followed by a digit (e.g. v1.0.0)" >&2
+          if [[ ! "$TAG" =~ ^v[0-9] ]]; then
+            echo "Release tag '$TAG' must start with 'v' followed by a digit (e.g. v1.0.0)" >&2
             exit 1
           fi
-          tag="${GITHUB_REF_NAME#v}"
+          tag="${TAG#v}"
           pkg_version=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
           if [ "$tag" != "$pkg_version" ]; then
             echo "Release tag ($tag) does not match pyproject.toml version ($pkg_version)" >&2
@@ -65,5 +81,10 @@ jobs:
           name: dist
           path: dist/
 
+      # v1.13.0's bundled twine rejects `Metadata-Version: 2.5`, which current
+      # hatchling emits: `InvalidDistribution: '2.5' is not a valid metadata
+      # version`. The build job's own `twine check --strict` passes, because it
+      # pip-installs a current twine — so the failure appears only at upload,
+      # after the tag is already public.
       - name: Publish via Trusted Publishing
-        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

.github/workflows/release.yml

@@ -4,6 +4,15 @@ on:
   push:
     tags:
       - 'v[0-9]*'
+  # Repair the Release for a tag that already exists, without moving it. See
+  # RELEASING.md, "If a release workflow fails" — added alongside this trigger,
+  # since a capability nobody can find is not much better than not having it.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing tag to create or update a Release for (e.g. v1.2.3)
+        required: true
+        type: string
 
 permissions:
   contents: write
@@ -12,8 +21,13 @@ jobs:
   release:
     name: Create GitHub Release
     runs-on: ubuntu-latest
+    env:
+      # The tag being released, whether it arrived by push or by dispatch.
+      TAG: ${{ inputs.tag || github.ref_name }}
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          ref: ${{ inputs.tag || github.ref_name }}
 
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
@@ -23,15 +37,15 @@ jobs:
         id: meta
         run: |
           pkg_name=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['name'])")
-          pkg_version="${GITHUB_REF_NAME#v}"
+          pkg_version="${TAG#v}"
           echo "name=${pkg_name}" >> "$GITHUB_OUTPUT"
           echo "version=${pkg_version}" >> "$GITHUB_OUTPUT"
 
       - name: Extract changelog notes
         id: notes
         run: |
           set -euo pipefail
-          version="${GITHUB_REF_NAME#v}"
+          version="${TAG#v}"
           if [[ -f CHANGELOG.md ]]; then
             body="$(python scripts/extract-changelog.py "$version")"
           else
@@ -47,8 +61,14 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631 # v2.2.2
         with:
-          tag_name: ${{ github.ref_name }}
+          tag_name: ${{ inputs.tag || github.ref_name }}
           name: ${{ steps.meta.outputs.name }} ${{ steps.meta.outputs.version }}
           body: ${{ steps.notes.outputs.body }}
           generate_release_notes: false
-          make_latest: true
+          # Let GitHub decide by tag date/semver rather than by run order. On a
+          # push the tag is the newest version and becomes latest; on a dispatch
+          # repairing an older tag, a newer release keeps the badge. Note `false`
+          # is not "leave alone" — it explicitly marks a release NOT latest, so
+          # gating on the event would demote the newest tag in the very case this
+          # trigger exists for: repairing its Release after a failed push run.
+          make_latest: legacy

RELEASING.md

@@ -34,6 +34,27 @@ Pushing a `vX.Y.Z` tag triggers two workflows:
 | `publish.yml` | Build wheel/sdist and publish to PyPI |
 | `release.yml` | Create the GitHub Release with notes from `CHANGELOG.md` |
 
+## If a release workflow fails
+
+Both workflows also accept a manual re-run against an existing tag, so a failure
+unrelated to the code — a stale action pin, a PyPI outage — does not require
+deleting the tag or burning a version number:
+
+```bash
+gh workflow run "Publish to PyPI" --ref main -f tag=vX.Y.Z
+gh workflow run "GitHub Release"  --ref main -f tag=vX.Y.Z
+```
+
+`--ref main` selects the workflow *definition*, so a fix to the workflow file
+itself is picked up; everything it runs — including `scripts/extract-changelog.py`
+— still comes from the tag, since that is what is being built and released. The
+two refs serve different purposes, which is why they can differ.
+
+A version is only spent once PyPI has accepted an upload. If the publish failed
+before that, the same version can still be published — check with
+`curl -s -o /dev/null -w '%{http_code}' https://pypi.org/pypi/<pkg>/<version>/json`
+returning 404.
+
 ## Enforcement
 
 - **PR check** (`check-release.yml`): if `pyproject.toml` version changes, `CHANGELOG.md` must contain a matching `## [X.Y.Z]` section.