Releasing
How to cut a new ipa-forge release: PyPI Trusted Publishing and GitHub Releases via CI.
How to cut a new ipa-forge release. The pipeline is
release.yml;
it reuses the same lint+test jobs as CI
(checks.yml)
before it builds or publishes anything.
One-time setup
Already done for 0.1.0 (published manually via twine upload with an
account-scoped API token). From 0.1.1 onward the pipeline publishes via
PyPI Trusted Publishing (OIDC) instead — no long-lived token is stored
as a GitHub secret. Revoke the manual token (pypi.org → Account settings →
API tokens) once this is set up.
PyPI
On the ipa-forge project page →
Publishing → add a trusted publisher:
- Owner:
nandan-varma, Repository:ipa-forge - Workflow name:
release.yml - Environment name:
pypi
GitHub
Repo Settings → Environments → New environment named pypi. Optionally add
required reviewers here — that turns the publish job into a
manual-approval gate before anything goes to PyPI, which is worth turning
on given publishing is irreversible (PyPI never allows re-uploading a
version).
Both steps only need to happen once; every future tagged release reuses them automatically.
Cutting a release
Bump the version
Bump version in pyproject.toml, add a new ## [X.Y.Z] - YYYY-MM-DD
section to CHANGELOG.md. Normal PR to main.
Let CI run
The tag push triggers release.yml: lint+test → verify the tag matches
pyproject.toml's version → build sdist/wheel → twine check → publish
to PyPI → create a GitHub Release with the built artifacts attached.
Approve, if gated
If the pypi environment has required reviewers, approve the publish
job run in the Actions tab.
A tag that doesn't match pyproject.toml's version fails fast in the
version job before anything is built or published.