Python Release Playbook
Release candidates (RC)
Use the Release Python RC workflow in GitHub Actions:
- Go to Actions → Release Python RC
- Click "Run workflow"
- Enter target version (e.g.,
X.Y.Z) - The workflow infers the next RC (
X.Y.Z-rc.1,X.Y.Z-rc.2, …) and runs the full flow
What the workflow does:
- Creates branch
release/X.Y.Z-rc.1(one branch per RC) - Bumps all
pyproject.tomlversions from current to the RC version - Commits and pushes to that branch
- Creates tag
vX.Y.Z-rc.1pointing at the release branch - Tag push triggers Publish Python, which builds and publishes to PyPI
No PR required.
If you need to re-run publish (e.g., it failed): Go to Actions → Publish Python → Run workflow → select the release branch (e.g., release/X.Y.Z-rc.1) from the branch dropdown → Run.
Stable release steps
There is one path. create_release refuses to run unless every step below was followed.
bin/bump_version X.Y.Zon a branch from main. It bumps everypyproject.tomlanduv.lock.- Open a PR to main titled
chore: release vX.Y.Zorchore(py): release Python SDK vX.Y.Z. Its description is the release notes, published word for word. - Get it approved and merged.
bin/create_release X.Y.Z <PR_NUMBER> --dry-run, then without--dry-run.- Approve the publish at https://github.com/genkit-ai/genkit-python/actions/workflows/publish_python.yml. The tag push already started it; don't run it by hand.
pip index versions genkitshows X.Y.Z.
create_release runs every check before it changes anything and prints a fix for each failure:
- Merged into main: the PR is merged, and into main
- Title: matches
chore: release vX.Y.Zorchore(py): release Python SDK vX.Y.Z - Release notes: the description isn't empty
- Versions: every
packages/*/pyproject.tomlis at X.Y.Z in the merge commit - Tag:
vX.Y.Zdoesn't exist yet
It tags the PR's merge commit, not the tip of main, so anything merged later stays out of the release. Exit codes: 0 ok, 1 usage or environment, 2 a check failed and nothing changed.
To fix notes after release, edit the GitHub release: gh release edit vX.Y.Z --notes-file notes.md. The PR description isn't read again.
After 0.13.0: retire genkit-evaluators
genkit 1.0 removes evaluators (#6947). genkit-evaluators 0.13.0 is the last release and requires genkit>=0.13.0,<1. bump_version writes that floor; the steps above need no hand edits.
Every earlier release (0.9.0 through 0.12.0) requires genkit with no upper bound. The cap alone isn't enough: when 0.13.0 conflicts with genkit 1.0, pip and uv backtrack to an older genkit-evaluators, and those accept genkit 1.0. So, once v0.13.0 is on PyPI:
- Yank genkit-evaluators 0.9.0, 0.10.0, 0.11.0 and 0.12.0 on PyPI (Manage → Releases → Options → Yank). Reason:
unbounded genkit dependency; use 0.13.0. - Verify in a fresh venv:
bash
python3 -m venv /tmp/evals && /tmp/evals/bin/pip install genkit-evaluators
/tmp/evals/bin/pip list | grep -E '^genkit '
# => genkit 0.13.x
/tmp/evals/bin/pip show genkit-evaluators | grep Version
# => Version: 0.13.0
- Only then merge #6947.
Resolvers skip yanked versions unless pinned with ==, so existing exact pins keep installing.
Workflow: publish_python.yml
Triggers: Tag push (v*) or manual workflow_dispatch. When triggered by tag, it checks out the tag (which points at the release branch). When run manually, select the release branch (e.g., release/X.Y.Z-rc.1) from the "Use workflow from" dropdown — otherwise it will build from main.
Two jobs: publish → verify
- publish: Builds all packages with
uv build, then uploads to PyPI viapypa/gh-action-pypi-publish. All-or-nothing — if any build fails, the job fails. - verify:
pip install genkit==<version>+ import test.
Auth
OIDC trusted publishing. No API tokens. PyPI is configured to trust: Owner genkit-ai, Repository genkit-python, Workflow publish_python.yml, Environment pypi_github_publishing. Don't rename the workflow file or this breaks.