ci: skip PyPI publish when token is missing

Author: Guotong

.github/workflows/publish.yml

@@ -10,7 +10,7 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
-      id-token: write
+      contents: read
 
     steps:
       - name: Checkout
@@ -29,6 +29,13 @@ jobs:
           twine check dist/*
 
       - name: Publish to PyPI
+        if: ${{ secrets.PYPI_API_TOKEN != '' }}
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Skip PyPI publish (token not configured)
+        if: ${{ secrets.PYPI_API_TOKEN == '' }}
+        run: |
+          echo "PYPI_API_TOKEN is not set. Skipping package upload."
+          echo "To enable publish, add PYPI_API_TOKEN in repo Settings -> Secrets and variables -> Actions."

docs/release/publish-runbook.md

@@ -7,6 +7,20 @@
 - Replace `<YOUR_HANDLE>` in launch copies.
 - (Optional) Replace security email in `SECURITY.md`.
 
+## 0.5) Choose PyPI publish mode
+
+Option A (simplest): API token
+
+- In PyPI, create an API token (project-scoped recommended).
+- In GitHub repo: `Settings -> Secrets and variables -> Actions`
+- Add secret: `PYPI_API_TOKEN`
+
+Option B: Trusted Publisher (OIDC)
+
+- Configure Trusted Publisher on PyPI for this exact repo/workflow.
+- If claims do not match, you'll see `invalid-publisher`.
+- This repository currently defaults to API token mode.
+
 ## 1) Final local checks
 
 ```bash