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 (fresh wheel install → canonical demo → mkdocs build --strict → compose posture assert)
  • publish to PyPI (if configured)
  • build and attach Linux/Windows Studio zips to the GitHub Release
• Pre-release tags containing rc/a/b (e.g. v1.2.0rc1):
  • publish to TestPyPI (if configured)

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”).