ci: auto-publish releases by branch channel + auto-bump develop alpha version

.github/workflows/auto-bump-alpha-version.yml

@@ -0,0 +1,50 @@
+name: Auto-bump alpha version
+
+# Mechanically bumps the develop-channel `aN` alpha counter on the PR's own
+# head branch (never on develop/main, which stay branch-protected with no
+# bypass — see SPEC.md §V29tz/T32yy). Base-version bumps (major/minor/patch)
+# remain a human decision; `version-check.yml` stays as the enforcement
+# backstop for those cases and for forked PRs (read-only token there).
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches: [develop]
+    paths-ignore:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "**/*.md"
+
+permissions:
+  contents: write
+
+concurrency:
+  group: auto-bump-alpha-${{ github.head_ref }}
+  cancel-in-progress: true
+
+jobs:
+  bump:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.head_ref }}
+          fetch-depth: 0
+          fetch-tags: true
+
+      - uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Bump alpha version if needed
+        run: |
+          set -euo pipefail
+          git fetch origin --tags --force
+          version="$(uv run --no-project --with packaging --with tomli python scripts/bump_alpha_version.py --write)"
+          if git diff --quiet -- pyproject.toml; then
+            echo "no bump needed (already $version)"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git commit -m "chore: bump alpha version to $version"
+          git push origin "HEAD:refs/heads/${{ github.head_ref }}"

.github/workflows/auto-tag.yml

@@ -1,7 +1,8 @@
-name: Tag prerelease
+name: Tag and publish release
 
-# A merged develop/main commit supplies its own version. This workflow only
-# validates the channel and creates the matching git tag; it never commits.
+# A merged develop/main commit supplies its own version. This workflow validates
+# the channel, creates the matching git tag, and dispatches publication for the
+# appropriate package index.
 on:
   push:
     branches: [develop, main]
@@ -16,6 +17,7 @@ concurrency:
 
 permissions:
   contents: write
+  actions: write
 
 jobs:
   tag-merged-version:
@@ -37,16 +39,26 @@ jobs:
           uv run --no-project --with packaging python - "$GH_REF_NAME" <<'PY'
           import subprocess
           import sys
+          import os
           import tomllib
           from packaging.version import Version
 
           branch = sys.argv[1]
           with open("pyproject.toml", "rb") as file:
               version = tomllib.load(file)["project"]["version"]
           candidate = Version(version)
-          expected = "a" if branch == "develop" else "b"
-          if candidate.pre is None or candidate.pre[0] != expected:
-              raise SystemExit(f"{branch} requires {expected} prerelease, found {version}")
+          if branch == "develop":
+              if candidate.pre is None or candidate.pre[0] != "a":
+                  raise SystemExit(
+                      f"develop requires an alpha prerelease, found {version}"
+                  )
+              registry = "testpypi"
+          elif branch == "main":
+              if candidate.is_prerelease:
+                  raise SystemExit(f"main requires a stable release, found {version}")
+              registry = "pypi"
+          else:
+              raise SystemExit(f"unsupported release branch: {branch}")
 
           tags = subprocess.check_output(["git", "tag", "--list", "v*"], text=True).splitlines()
           tagged_versions = []
@@ -68,4 +80,21 @@ jobs:
           subprocess.run(["git", "tag", tag], check=True)
           subprocess.run(["git", "push", "origin", tag], check=True)
           print(f"created {tag}")
+          subprocess.run(
+              [
+                  "gh",
+                  "workflow",
+                  "run",
+                  "publish.yml",
+                  "--ref",
+                  branch,
+                  "--field",
+                  f"tag={tag}",
+                  "--field",
+                  f"registry={registry}",
+              ],
+              check=True,
+              env={**os.environ, "GH_TOKEN": os.environ["GITHUB_TOKEN"]},
+          )
+          print(f"dispatched {registry} publication for {tag}")
           PY

.github/workflows/publish.yml

@@ -7,8 +7,16 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Existing tag to publish to PyPI and cut a GitHub Release for"
+        description: "Existing release tag to publish and optionally release"
         required: true
+      registry:
+        description: "Package index to publish to"
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: pypi
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
@@ -74,19 +82,14 @@ jobs:
           python -m pytest
 
 
-  # Trusted Publisher must be configured once on the PyPI project's "Publishing"
-  # settings page (pending-publisher works before the first release exists),
-  # pointing at this repo/workflow/environment. No API token is stored here.
-  #
-  # Gated to manual dispatch only: CI verifies the built alpha/beta/rc
-  # artifact, while feature-branch .dev versions are uploaded locally by
-  # make publish-testpypi-dev. Going out to real PyPI (and cutting a GitHub
-  # Release) requires an explicit "Run workflow" dispatch naming the tag.
+  # Configure Trusted Publishers for this workflow in both package indexes:
+  # environment `testpypi` for alpha releases and `pypi` for stable releases.
+  # No API token is stored here.
   publish:
     needs: verify
     if: github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
-    environment: pypi
+    environment: ${{ inputs.registry }}
     permissions:
       id-token: write
     steps:
@@ -100,7 +103,13 @@ jobs:
           RELEASE_TAG: ${{ inputs.tag }}
         run: |
           set -euo pipefail
-          [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(a[0-9]+|b[0-9]+|rc[0-9]+)?$ ]] || {
+          registry="${{ inputs.registry }}"
+          if [[ "$registry" == "testpypi" ]]; then
+            tag_pattern='^v[0-9]+\.[0-9]+\.[0-9]+a[0-9]+$'
+          else
+            tag_pattern='^v[0-9]+\.[0-9]+\.[0-9]+$'
+          fi
+          [[ "$RELEASE_TAG" =~ $tag_pattern ]] || {
             echo "Invalid release tag: $RELEASE_TAG"
             exit 1
           }
@@ -113,10 +122,12 @@ jobs:
           }
 
       - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ inputs.registry == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}
 
   release:
     needs: publish
-    if: github.event_name == 'workflow_dispatch'
+    if: github.event_name == 'workflow_dispatch' && inputs.registry == 'pypi'
     runs-on: ubuntu-latest
     permissions:
       contents: write

.github/workflows/version-check.yml

@@ -38,9 +38,18 @@ jobs:
           with open("pyproject.toml", "rb") as file:
               version = tomllib.load(file)["project"]["version"]
           parsed = Version(version)
-          expected = "a" if target == "develop" else "b"
-          if parsed.pre is None or parsed.pre[0] != expected:
-              raise SystemExit(f"PR target {target} requires {expected} prerelease, found {version}")
+          if target == "develop":
+              if parsed.pre is None or parsed.pre[0] != "a":
+                  raise SystemExit(
+                      f"PR target {target} requires an alpha prerelease, found {version}"
+                  )
+          elif target == "main":
+              if parsed.is_prerelease:
+                  raise SystemExit(
+                      f"PR target {target} requires a stable release, found {version}"
+                  )
+          else:
+              raise SystemExit(f"unsupported PR target: {target}")
 
           tags = subprocess.check_output(["git", "tag", "--list", "v*"], text=True).splitlines()
           candidate = Version(version)
@@ -51,5 +60,5 @@ jobs:
                   continue
               if tagged >= candidate:
                   raise SystemExit(f"version {version} is not newer than existing tag {tag}")
-          print(f"{target}: {version} is a valid newer prerelease")
+          print(f"{target}: {version} is a valid newer release")
           PY