PyPI publishing (release workflow)

Helix publishes the helix-governance distribution via GitHub Actions in .github/workflows/release.yml.

This document is the setup checklist so PyPI publishing is boring and repeatable.

How publishing works

• Tags vX.Y.Z:
  • build sdist+wheel
  • run the smoke gate:
    • python tools/smoke_package.py --wheel "dist/*.whl" --venv-dir .venv_smoke
    • python demo/canonical/run_governance_registry_demo.py --out artifacts/release_smoke/demo
    • posture defaults match policy in deploy/production.env.example and deploy/docker-compose.yml
  • publish to PyPI (if configured)
  • build and attach Linux/Windows/macOS Studio zips to the GitHub Release
• Pre-release tags containing rc/a/b (e.g. v1.2.0rc1):
  • publish to TestPyPI (if configured)
  • still run the same build_dist + smoke jobs before publish

One-time setup

Trusted Publishing (OIDC)

1. In PyPI, create or open the project for helix-governance.
2. Add a Trusted Publisher for GitHub Actions pointing at:
   • repo: omniscoder/Helix
   • workflow: .github/workflows/release.yml
   • environment: pypi
3. In TestPyPI, do the same with:
   • environment: testpypi
4. In GitHub:
   • protect the pypi environment with reviewers (optional but recommended)
   • do not store PyPI API tokens in repo secrets (OIDC-only)

Pre-tag smoke gate (recommended)

Run the exact release smoke on the exact commit you intend to tag:

• GitHub Actions → workflow release → Run workflow
  • ref: <commit_sha>
  • mode: smoke

Only tag if the smoke run is green.

Yank policy (if needed)

If a release is published to PyPI and breaks installs, yank it (do not delete) and point users to the fixed tag.

• PyPI UI: yanking is per-file/version; include a short reason (e.g. “missing dependency; install fails”).