ci: publish to PyPI from a GitHub release, by trusted publishing

publish.yml follows the release workflow of the other toolboxes: verify that
the tag is the version in pyproject.toml and that the tagged commit is on
main, build the sdist and wheel, twine check, install the wheel into a clean
environment and run a path query, then upload with OIDC from the pypi
environment.  skip_existing makes a re-run harmless.  The default token is
read-only.

The docs job of ci.yml can be run by hand, from main only.  The manual
twine-upload Makefile target is gone, as a release does it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

Author: petercorke

.github/workflows/ci.yml

@@ -82,7 +82,7 @@ jobs:
           verbose: true
 
   docs:
-    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
     needs: unittest
     runs-on: ubuntu-latest
     steps:

.github/workflows/publish.yml

@@ -1,45 +1,114 @@
+# Build and publish to PyPI when a GitHub release is created, or on manual trigger.
+# Uses OIDC trusted publishing, so no PyPI token is stored.  The trusted publisher
+# on PyPI is: owner petercorke, repository pgraph-python, workflow publish.yml,
+# environment pypi.  Pure Python package, so one universal wheel and an sdist.
+#
+# To release: make sure main has the version in pyproject.toml, then create a
+# GitHub release whose tag is v<version> on main.
+
 name: Publish to PyPI
 
 on:
   release:
-    types: [published]
+    types: [created]
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
+  verify_version:
+    name: Verify tag matches package version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Check version
+        # Skip on manual workflow_dispatch runs (no release tag exists)
+        if: github.event_name == 'release'
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "Tag version    : $TAG"
+          echo "Package version: $PKG"
+          [ "$TAG" = "$PKG" ] || { echo "ERROR: tag $GITHUB_REF_NAME does not match pyproject.toml version $PKG"; exit 1; }
+      - name: Check the tagged commit is on main
+        if: github.event_name == 'release'
+        run: |
+          git fetch origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main \
+            || { echo "ERROR: $GITHUB_SHA is not on main, so it was not reviewed and tested there"; exit 1; }
+
   build:
+    name: Build sdist and wheel
+    needs: verify_version
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
-      - name: Install build tooling
-        run: |
-          python -m pip install --upgrade pip
-          pip install build twine
+
       - name: Build sdist and wheel
-        run: python -m build
+        run: pipx run build
+
       - name: Check metadata
-        run: twine check dist/*
-      - name: Upload build artifacts
-        uses: actions/upload-artifact@v4
+        run: pipx run twine check dist/*
+
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
 
-  publish:
+  smoke_test:
+    name: Smoke-test wheel
     needs: build
     runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Install the wheel (pulls dependencies from PyPI)
+        run: pip install dist/*.whl
+
+      - name: Smoke test
+        run: |
+          python - <<'PY'
+          from importlib.metadata import version
+          import pgraph
+
+          g = pgraph.UGraph()
+          g.add_vertex(coord=[0, 0], name="a")
+          g.add_vertex(coord=[3, 4], name="b")
+          g.add_edge("a", "b")
+          path, length, _ = g.path_Astar("a", "b")
+          assert length == 5.0, length
+          print("OK", version("pgraph-python"), length)
+          PY
+
+  upload_pypi:
+    name: Publish to PyPI
+    needs: [build, smoke_test]
+    runs-on: ubuntu-latest
     environment:
       name: pypi
       url: https://pypi.org/project/pgraph-python/
     permissions:
-      id-token: write  # required for PyPI trusted publishing (OIDC)
+      id-token: write   # required for OIDC trusted publishing
     steps:
-      - name: Download build artifacts
-        uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
-          path: dist/
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+          path: dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip_existing: true