Add GitHub Actions PyPI release workflow

Author: nickmoreton

.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Validate release tag matches package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          PACKAGE_VERSION="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          EXPECTED_TAG="v${PACKAGE_VERSION}"
+
+          if [ "${RELEASE_TAG}" != "${EXPECTED_TAG}" ]; then
+            echo "Release tag ${RELEASE_TAG} does not match expected tag ${EXPECTED_TAG} derived from project version ${PACKAGE_VERSION}."
+            exit 1
+          fi
+
+      - name: Validate release commit is on main
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          git fetch --no-tags origin main
+          RELEASE_SHA="$(git rev-list -n 1 "refs/tags/${RELEASE_TAG}")"
+
+          if ! git merge-base --is-ancestor "${RELEASE_SHA}" origin/main; then
+            echo "Release tag ${RELEASE_TAG} points to commit ${RELEASE_SHA}, which is not contained in origin/main."
+            exit 1
+          fi
+
+      - name: Build source distribution and wheel
+        run: uv build --sdist --wheel --out-dir dist
+
+      - name: Validate built artifacts
+        run: uvx twine check dist/*
+
+      - name: Upload built distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/project/wagtail-honeypot/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

CHANGELOG

@@ -14,6 +14,7 @@ All notable changes to this project will be documented in this file.
 - Update contributor and agent documentation for the new development workflow
 - Update the honeypot field documentation for the `aria-hidden="true"` accessibility attribute
 - Sync the Ruff pre-commit hook version with the locked Ruff release and correct the developer doc Wagtail baseline
+- Publish PyPI releases from GitHub Actions with trusted publishing and a protected `pypi` environment
 
 ## [1.2.1] - 2026-02-05
 

docs/developer.md

@@ -70,6 +70,46 @@ make lint
 make format
 ```
 
+## Release process
+
+PyPI releases are published from GitHub Actions after a GitHub Release is published.
+
+Prepare the release from `main`, not `release`:
+
+```bash
+git switch main
+git pull origin main
+```
+
+Before creating the release:
+
+- Update `project.version` in `pyproject.toml`
+- Update `CHANGELOG` for the release
+- Ensure the commit you intend to release is on `main`
+
+Create and push the release tag using the `vX.Y.Z` format:
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+```
+
+Then publish the matching GitHub Release for that tag. The `Release` workflow will:
+
+- Verify the GitHub Release tag exactly matches `v{project.version}`
+- Verify the tagged commit is contained in `origin/main`
+- Build the sdist and wheel
+- Run `twine check`
+- Wait for approval on the GitHub `pypi` environment before uploading to PyPI
+
+Repository setup required for trusted publishing:
+
+- Add a GitHub environment named `pypi`
+- Protect that environment with the required approval rules for your release process
+- Register the PyPI trusted publisher for repository `nm-packages/wagtail-honeypot`, workflow `.github/workflows/release.yml`, and environment `pypi`
+
+After approving the `pypi` environment job, confirm both the source distribution and wheel appear on PyPI.
+
 ## Dependency management
 
 Use `uv` to change contributor dependencies and keep the lockfile in sync: