build: harden release and publish workflows

Author: markoblogo

.github/workflows/ci.yml

@@ -10,9 +10,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

.github/workflows/pypi-publish.yml

@@ -0,0 +1,42 @@
+name: id-protocol-pypi-publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Release tag to publish from
+        required: true
+        type: string
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Download release artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name || inputs.release_tag }}
+        run: |
+          mkdir -p dist
+          gh release download "${RELEASE_TAG}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --dir dist \
+            --pattern "*.whl" \
+            --pattern "*.tar.gz"
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/release.yml

@@ -13,9 +13,9 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 
@@ -32,7 +32,16 @@ jobs:
         run: make release-check
 
       - name: Publish GitHub release
-        uses: softprops/action-gh-release@v2
-        with:
-          files: |
-            dist/*
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "${GITHUB_REF_NAME}" --repo "${GITHUB_REPOSITORY}" >/dev/null 2>&1; then
+            gh release upload "${GITHUB_REF_NAME}" dist/* \
+              --repo "${GITHUB_REPOSITORY}" \
+              --clobber
+          else
+            gh release create "${GITHUB_REF_NAME}" dist/* \
+              --repo "${GITHUB_REPOSITORY}" \
+              --title "${GITHUB_REF_NAME}" \
+              --generate-notes
+          fi

README.md

@@ -41,6 +41,7 @@ Proof page:
 Release/install path:
 - `docs/RELEASES.md`
 - tagged GitHub release flow with `sdist`/`wheel` artifacts
+- PyPI publish workflow prepared for trusted publishing once package naming is finalized
 
 ## Choose One Path
 

docs/RELEASES.md

@@ -75,15 +75,42 @@ Workflow file:
 .github/workflows/release.yml
 ```
 
+## PyPI Publishing Flow
+
+PyPI publishing is separated from GitHub release creation.
+
+Workflow file:
+
+```text
+.github/workflows/pypi-publish.yml
+```
+
+Flow:
+
+1. a GitHub release is published
+2. the PyPI workflow downloads the release assets
+3. the workflow publishes them to PyPI via trusted publishing
+
+Before enabling real publication, configure:
+
+1. the final package name on PyPI
+2. a trusted publisher for `markoblogo/ID`
+3. the `pypi` GitHub environment, ideally with approval protection
+
+This separation is intentional:
+- GitHub release remains the canonical first publication step
+- PyPI publication stays auditable and can be approval-gated
+
 ## Current Release Posture
 
 - installable from source via `pip install .` or built artifacts in `dist/`
 - lightweight wrapper CLI via `idctl`
 - tagged GitHub release flow for `sdist`/`wheel`
-- no PyPI, Homebrew, or npm publication yet
+- PyPI publish workflow present, pending final package-name/trusted-publisher setup
+- no Homebrew or npm publication yet
 
 ## Recommended Next Release Steps
 
-1. Publish artifacts to PyPI once the package name and maintenance policy are stable.
+1. Finalize the PyPI package name and configure trusted publishing.
 2. Decide whether Homebrew or `pipx` should be a first-class install path.
 3. Decide whether `idctl` stays thin or grows a richer UX.