Releasing tranche on PyPI (via CI)

Releases are published by GitHub Actions. You generally don’t need to build or upload locally.

Prerequisites (one-time)

  • Choose a unique PyPI distribution name in pyproject.toml ([project].name).

  • Configure publishing auth (choose one):

    • API tokens: add repo secrets PYPI_API_TOKEN and (optional) TEST_PYPI_API_TOKEN.

    • Trusted Publishing (OIDC): enable a Trusted Publisher on PyPI. The workflow already grants id-token: write. If PyPI asks for an “Environment name,” use pypi (the workflow sets it by default, and testpypi for manual TestPyPI runs).

  • Optional: create GitHub Environments named pypi and testpypi to gate runs.

Normal release flow

  1. Bump the version in tranche/version.py and commit.

  2. Tag the release (no leading v) and push the tag:

git tag -a 0.1.1 -m "tranche 0.1.1"
git push origin 0.1.1

This triggers .github/workflows/publish.yml to:

  • build sdist and wheel,

  • check metadata,

  • publish to PyPI.

Publishing also runs if you publish a GitHub Release for that tag.

Optional: publish to TestPyPI

Use the manual workflow and choose testpypi:

  1. GitHub → Actions → “Build and publish to PyPI” → Run workflow → repository: testpypi.

  2. (Optional) Verify install from TestPyPI in a clean env.

Troubleshooting

  • 403 “not allowed to upload to project”: the name is taken on PyPI. Pick a new [project].name or pursue a PEP 541 transfer.

  • 409 “File already exists”: bump __version__ and re-tag.

  • Build/metadata failures: open the failed workflow, check the “Build” or “twine check” step logs.

  • Python compatibility: controlled by requires-python in pyproject.toml (>=3.10).

Optional local verification

If you want to sanity check locally:

python -m build
python -m twine check dist/*

This project is pure Python and produces a universal wheel (py3-none-any).