ci: add manual PyPI trusted publishing

Add a workflow_dispatch-only PyPI publish path backed by Trusted Publishing docs and distribution policy tests.

Author: saagpatel

.github/workflows/README.md

@@ -16,6 +16,23 @@ Steps:
 
 No secrets are required for CI.
 
+## `pypi.yml` — Manual PyPI Publish
+
+Runs manually via `workflow_dispatch` after PyPI Trusted Publishing has been
+configured for this repository. It does not run on normal pushes or tags.
+
+Steps:
+1. Validate that the requested ref is a `v*` release tag.
+2. Build the wheel and source distribution from that tag.
+3. Run `twine check`.
+4. Upload the checked distributions as a workflow artifact.
+5. Publish from the protected `pypi` environment using PyPI Trusted Publishing.
+
+No PyPI token secret is required. The publish job uses GitHub OIDC with
+`id-token: write`, which must match the PyPI Trusted Publisher configuration:
+owner `saagpatel`, repository `GithubRepoAuditor`, workflow `pypi.yml`, and
+environment `pypi`.
+
 ## `audit.yml` — Manual Automated Audit
 
 Runs manually via `workflow_dispatch`. The automatic weekly schedule is disabled while the repository remains private to avoid recurring GitHub Actions billing.

.github/workflows/pypi.yml

@@ -0,0 +1,69 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Release tag to publish, for example v0.1.1"
+        required: true
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Validate release ref
+        run: |
+          case "${{ inputs.ref }}" in
+            v*) ;;
+            *) echo "PyPI publishes must use a PEP 440-compatible v* release tag."; exit 1 ;;
+          esac
+
+      - name: Checkout release tag
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.ref }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Twine check
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish:
+    name: Publish distributions
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: python-distributions
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

CHANGELOG.md

@@ -8,6 +8,8 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Changed
+- Added a manual PyPI Trusted Publishing workflow that builds a release tag and
+  publishes from a protected `pypi` environment after PyPI is configured.
 - Made PyPI publishing explicitly opt-in while keeping GitHub Releases as the supported public distribution path.
 - Added PyPI-ready package metadata and public distribution status documentation.
 

docs/distribution.md

@@ -32,16 +32,21 @@ The repository is prepared for a future PyPI release:
 - `make dist-check` runs `twine check`
 - `scripts/release.sh` builds and checks artifacts by default
 - `scripts/release.sh --publish-pypi` is the only script path that uploads to PyPI
+- `.github/workflows/pypi.yml` is a manual Trusted Publishing workflow for a
+  release tag, using the `pypi` environment and short-lived OIDC credentials
 
 ## Activation Checklist
 
 Before the first PyPI release:
 
 1. Recheck that the `github-repo-auditor` PyPI name is still available.
-2. Create the PyPI project through a first upload or configure Trusted Publishing.
-3. Prefer PyPI Trusted Publishing from GitHub Actions over long-lived API tokens.
+2. Configure PyPI Trusted Publishing for owner `saagpatel`, repository
+   `GithubRepoAuditor`, workflow `pypi.yml`, and environment `pypi`.
+3. Protect the GitHub `pypi` environment so publishing requires intentional
+   approval.
 4. Run the standard and distribution gates from [release-gates.md](release-gates.md).
-5. Publish the same version that is tagged on GitHub.
+5. Open **Actions -> Publish to PyPI -> Run workflow** and enter the release tag,
+   for example `v0.1.1`.
 6. Smoke-test `pipx install github-repo-auditor` or `uv tool install github-repo-auditor`.
 
 Until that checklist is complete, GitHub Releases remain the supported public

docs/release-gates.md

@@ -157,6 +157,9 @@ All three must pass before tagging:
   `scripts/release.sh` builds and checks artifacts by default; it uploads only when
   run as `scripts/release.sh --publish-pypi` with valid credentials. CI only checks
   and uploads to GitHub Releases.
+- After PyPI Trusted Publishing is configured, prefer the manual `Publish to PyPI`
+  workflow over local token-based uploads. It builds the release tag in one job and
+  publishes from a separate `pypi` environment job with `id-token: write`.
 - The `[serve]` extra is not bundled in the shiv binary by default. Users who need the
   web UI should install from the GitHub source with the `[serve]` extra or use a local
   editable clone.

tests/test_distribution_policy.py

@@ -33,8 +33,23 @@ def test_distribution_docs_name_supported_public_channel() -> None:
     distribution_doc = (ROOT / "docs" / "distribution.md").read_text()
     readme = (ROOT / "README.md").read_text()
     release_gates = (ROOT / "docs" / "release-gates.md").read_text()
+    workflows_readme = (ROOT / ".github" / "workflows" / "README.md").read_text()
 
     assert "GitHub Releases remain the supported public" in distribution_doc
     assert "PyPI publishing is not active yet" in distribution_doc
     assert "docs/distribution.md" in readme
     assert "scripts/release.sh --publish-pypi" in release_gates
+    assert "pypi.yml" in workflows_readme
+    assert "id-token: write" in workflows_readme
+
+
+def test_pypi_workflow_is_manual_trusted_publishing_only() -> None:
+    workflow = (ROOT / ".github" / "workflows" / "pypi.yml").read_text()
+
+    assert "workflow_dispatch:" in workflow
+    assert "push:" not in workflow
+    assert "environment: pypi" in workflow
+    assert "id-token: write" in workflow
+    assert "pypa/gh-action-pypi-publish@release/v1" in workflow
+    assert "actions/upload-artifact" in workflow
+    assert "actions/download-artifact" in workflow