Releasing the A2UI Python SDKs
This skill turns a one-line request such as "release a2ui-core patch" or "release the Python SDKs" into the full release sequence.
Publishing is done by the Release Python SDKs workflow. This skill does not reimplement any of it. Its job is the part the workflow cannot do for itself: choosing the bump, catching the problems that a workflow run would discover too late, and following through afterwards.
Background for anything not covered here: docs/contributing/release/release.md.
[!CAUTION] Publishing to PyPI is irreversible. A version can be yanked but never reused or deleted. Step 5 is a mandatory stop. Never dispatch a run with
dry_run: falsewithout an explicit go-ahead from the maintainer in the current conversation.
What runs where
The workflow performs the release. Nothing here does. Building, tagging,
pushing tags, staging in the Artifact Registry and triggering the Exit Gate all
happen inside release-pypi.yml, and only there. It could not be otherwise: the
Exit Gate authenticates by matching the OIDC claim
…/release-pypi.yml@refs/heads/main, so a local upload has no credentials to
use.
| Run locally | Run by the workflow |
|---|---|
release_version.py notes |
release_version.py plan (authoritative) |
release_version.py plan (preview only) |
release_version.py check |
release_version.py check (preview only) |
release_version.py cut-changelog |
gh workflow run, gh run view, gh pr list |
release_artifacts.py, confirm_pypi.py |
uv build, twine upload, git tag, git push |
The local calls are limited to the read-only subcommands notes, next,
current, tag, plan and check. They exist to answer two questions before
spending a CI run: is there anything to release, and will preflight reject it.
[!IMPORTANT] A local
planis a prediction, not the release. It is computed from the tags in the local checkout, so it is only as current as the last fetch — which is why Step 2 fetches first. The plan the workflow computes is the one that counts, and Step 4 reads it back out of the run before anyone approves it.
Never run cut-changelog --write, git tag, git push, uv build or twine
by hand to perform a release. If the workflow cannot do it, fix the workflow.
[!IMPORTANT] One exception, and it is deliberate: the changelog pull request has to be opened by a person, not by the workflow. GitHub does not start workflow runs for events caused by
GITHUB_TOKEN, so a pull request the workflow opened would never get the required checks and could never be merged. The workflow pushes the branch; Step 7 opens the pull request.
Step 1: Check environment prerequisites
Check that your local environment meets these prerequisites before proceeding.
The preflight check in Step 3 (release_version.py check) also validates these
automatically and stops with an Action needed: message for each one that
fails. They are skipped in GitHub Actions, where they do not apply.
An a2ui checkout. Run from your clone of
a2ui-project/a2ui. The script finds the repository root itself, so a subdirectory works (it warns), but the commands below use paths relative to the root.Python 3.11+. The script reads
pyproject.tomlwith the standard librarytomllib. If your systempython3is older, run it through the project toolchain instead:uv run python .github/scripts/release_version.py ....GitHub CLI (
gh), installed, authenticated withgithub.com, and with write access toa2ui-project/a2ui. It dispatches and watches the workflow and opens the changelog pull request.Git identity.
git config user.nameandgit config user.emailmust be set, so the changelog commit and pull request pass CLA verification.A remote that points at
a2ui-project/a2ui. It may be calledoriginin a direct clone orupstreambeside a fork; the script finds it by URL. The commands below call it${REMOTE}:REMOTE=$(git remote -v | awk '/a2ui-project\/a2ui(\.git)?\/? \(fetch\)/ {print $1; exit}')
Step 2: Work out what is being released
Two things are needed: PACKAGE and BUMP (patch, minor, or major).
PACKAGE names the packages to release, either as a comma-separated list of
package names or as all:
- One package:
a2ui-agent-sdk - Several packages:
a2ui-a2a,a2ui-adk - Every package:
all(a2ui-core,a2ui-agent-sdk,a2ui-a2a,a2ui-adk)
The workflow publishes the listed packages in dependency order (a2ui-core,
a2ui-agent-sdk, a2ui-a2a, a2ui-adk), whatever order they are listed in.
Derive PACKAGE and BUMP from the changelogs. Never infer them from the
phrasing of the request.
Fetch first. Versions are derived from tags, so every number below is wrong if the checkout is behind:
git fetch "${REMOTE}" main --tagsfor package in a2ui-core a2ui-agent-sdk a2ui-a2a a2ui-adk; do
echo "== ${package}"
python3 .github/scripts/release_version.py notes --package "${package}"
doneChoose the packages. Release only those with a non-empty ## Unreleased.
Empty output means that package has nothing to release, whatever was asked for.
A plural request such as "release the Python SDKs" does not mean all. List
exactly the packages with pending entries, for example
a2ui-agent-sdk,a2ui-a2a. If only one has pending entries, that one is the
release. If none does, stop and say so.
Check the exit status, not just the output. The two failure shapes are different answers:
| Result | Meaning | Do |
|---|---|---|
| exit 0, output | Entries pending | Release this package |
| exit 0, no output | ## Unreleased is empty |
Skip this package |
exit 1, error: on stderr |
Changelog is malformed, usually a missing ## Unreleased heading |
Stop. Report it and do not dispatch. |
[!NOTE] Dispatching a package whose
## Unreleasedis empty is not dangerous, just wasteful. The plan builds, then preflight rejects the empty package and the run fails several minutes in. The check above costs a second.
Choose the bump. Read the entries. Fixes only means patch and new
features mean minor. A breaking change means minor while the package is
below 1.0, and major from 1.0 on. Preview the result with plan,
which returns exactly what the workflow will compute — version, tag and release
notes for every selected package:
python3 .github/scripts/release_version.py plan --package "${PACKAGE}" --bump "${BUMP}"[!IMPORTANT] One run applies one bump level to every listed package. The workflow takes a single
bumpinput, sobuild_planraises every version by the same amount. When the packages warrant different levels — say fixes ina2ui-coreand a feature ina2ui-agent-sdk— there is no single right answer. Put the choice to the maintainer:
- Take the higher level for every listed package. One release, one changelog pull request. The cost is an over-bumped version on the quieter packages.
- Run one release per bump level. Correct versioning, but the changelog pull request from each run must be merged before starting the next, or the Step 3 guard will block it. Release in dependency order:
a2ui-core,a2ui-agent-sdk,a2ui-a2a,a2ui-adk.
[!IMPORTANT] A minor or major
a2ui-corebump may need a pin change first.a2ui-agent-sdkdeclares a range such asa2ui-core>=0.3.0,<0.4.0in a2ui_agent/pyproject.toml. If the proposeda2ui-coreversion falls outside it, widen the pin in its own pull request and merge it tomainbefore dispatching. When doing so, also updatetool.hatch.version.fallback-versionin the dependency'spyproject.toml(and any co-released packages) so tagless checkouts and shallow CI clones (fetch-depth: 1) satisfy the new constraint. The workflow releasesmainas it is and cannot change package files during the run. Step 3 rejects the release until this is done.The same applies down the chain:
a2ui-a2aanda2ui-adkpina2ui-agent-sdkin theirpyproject.toml, anda2ui-adkpinsa2ui-a2ain itsa2aextra. A new version of a package must fall inside every pin on it.
[!IMPORTANT] A dependent needs its dependencies on PyPI. Releasing
a2ui-a2aora2ui-adkon its own requires the releaseda2ui-agent-sdk(and, fora2ui-adk,a2ui-a2a) to satisfy its pins already. If it does not, release the dependency first, or list it in the same run. Step 3 reports this as "has not been released yet" or "requires ..., but the latest release ... is ...".First release of a brand-new package. A package with no tag yet starts from
0.0.0, so use aminorbump to release0.1.0. Before its first release, the package name must be added to the OSS Exit Gate allowlist fora2ui/pypiand registered as a Pending Publisher onhttps://pypi.org/manage/account/publishing/under the Google tab with emaila2ui-py@oss-exit-gate-prod.iam.gserviceaccount.comand an empty subject (seego/a2ui-release#pypi). PyPI indexes Google Cloud Pending Publishers uniquely by(email, sub), so only one Pending Publisher can be registered at a time. Do not release two brand-new packages in the same manifest: register and publish them one at a time so the first upload promotes its Pending Publisher to a project-scoped Trusted Publisher before registering the second.
Put the proposal to the maintainer with ask_question, showing the pending
entries and the resulting versions, and let them correct it.
Step 3: Preflight locally
These checks cost seconds and catch the failures that are expensive to hit mid-run. Run all of them before dispatching anything.
1. The environment and the checkout. check runs these for you (see
Step 1: Check environment prerequisites); this is what it looks for and why:
- No outstanding changelog branch from a previous release on
${REMOTE}. Until the last release's changelog lands, its entries are still under## Unreleased, and this release would repeat them. It checks the branch, not the pull request, because the release stops at the branch and there may be no pull request yet. The repository deletes branches on merge, so no branch means the last changelog landed. If one is found, get that change merged (open the pull request if nobody has), then start over from Step 2, because the pending entries will have changed. - The released packages match
${REMOTE}/main. The workflow builds frommain, sopython/a2ui_core,python/a2ui_agent,python/a2ui_a2aandpython/a2ui_adkmust be identical to it. Uncommitted edits, or a local commit that is not merged yet (a widened pin, say), would make the local preview describe a release that is not the one that will go out. Other paths in the checkout do not matter.
If it reports any of these, or any of the Environment Prerequisites, stop and say what was found.
2. The repository's own preflight passes. The package checks (changelog, tag, and pin) are the ones the workflow runs, so a failure in them here is a failure there:
# Check using bump level (comma-separated package names, or 'all'):
python3 .github/scripts/release_version.py check --package "${PACKAGE}" --bump "${BUMP}"
# Or check a specific version directly (single package only):
python3 .github/scripts/release_version.py check --package "${PACKAGE}" --version "${VERSION}"It rejects an empty ## Unreleased, a version that already has a tag, a version
outside the range that another package pins it to, and a dependency on another
package of this repository that no released version (or no version in the same
run) satisfies. With several packages and --bump, it evaluates every listed
package and their cross-dependency pins in a single step.
If preflight reports a pin problem, stop: see the pin notes in Step 2.
Step 4: Dry run
A dry run builds and stages the artifacts in the Exit Gate Artifact Registry, removes them again, and pushes nothing.
gh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \
-f package="${PACKAGE}" -f bump="${BUMP}" -f dry_run=trueWait a few seconds, then find the run and watch it:
gh run list --repo a2ui-project/a2ui --workflow=release-pypi.yml --limit 1 \
--json databaseId,status,url
gh run watch "${RUN_ID}" --repo a2ui-project/a2ui --exit-status[!TIP] Use the full
databaseId. A truncated run ID returns 404.
If it fails, read the failing step's log and consult Troubleshooting below before retrying.
When it passes, read back the plan the run actually computed. The dry run does not upload the plan artifact, and step summaries are not available over the API, but the plan step prints the JSON into the log:
gh run view "${RUN_ID}" --repo a2ui-project/a2ui --log \
| grep -A 20 'Build the release plan'Compare it against the local plan output from Step 2. They are computed the
same way and should agree. If they differ, a tag landed in between — stop and
work out why before going any further.
Step 5: Confirm with the maintainer
Stop here. Show the maintainer:
- the exact versions and tags from the dry run's plan,
- the changelog entries that will become the release notes,
- that the dry run passed.
Quote the version numbers in full, for example a2ui-agent-sdk 0.7.0. Do not
describe the release only as "a minor bump" — the bump level is the input, the
version is the irreversible consequence, and it is the version the maintainer
needs to approve.
Then ask for explicit confirmation to publish. Proceed only on a clear yes.
Step 6: Publish
AUTHOR_NAME=$(git config user.name)
AUTHOR_EMAIL=$(git config user.email)
gh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \
-f package="${PACKAGE}" -f bump="${BUMP}" -f dry_run=false \
-f author_name="${AUTHOR_NAME}" -f author_email="${AUTHOR_EMAIL}"Watch it as in Step 4. The run pushes the tags, stages the artifacts, uploads the manifest that triggers the Exit Gate, and creates the GitHub releases.
Four jobs follow:
| Job | What it does | If it fails |
|---|---|---|
build |
Runs tests and builds distributions | Test failure or malformed distribution. See Troubleshooting. |
release |
Stages, tags, and triggers publishing | Real failure. See Troubleshooting. |
confirm |
Polls PyPI, then links the GitHub releases | A timeout is not a failure. The hourly Confirm PyPI publication workflow finishes the job. |
changelog |
Pushes the changelog branch | Publishing already succeeded. Cut the changelog by hand and open the PR yourself. |
[!IMPORTANT] The run stays active for several minutes after
releasegoes green, and that is normal. Triggering the Exit Gate is not publishing. The Exit Gate works asynchronously and reports only by email, so theconfirmjob sits and polls PyPI every 30 seconds for up to 20 minutes waiting for the version to appear.
gh run watchblocks until all three jobs finish, so it is the wait. Let it run. Do not poll PyPI in a loop alongside it, and do not report the release as finished — or as failed — whileconfirmis still in progress.
Step 7: Follow through
A release is not done when the workflow goes green.
Confirm the version is live. The waiting has already happened on the runner, so read the
confirmjob's outcome rather than starting a fresh wait:confirmsucceeded — the version is on PyPI and the GitHub releases have been updated with links. Verify once and move on:curl -s -o /dev/null -w '%{http_code}\n' "https://pypi.org/pypi/${PYPI_NAME}/${VERSION}/json"200confirms it. A404here, afterconfirmreported success, is a CDN lag of a minute or two — wait briefly and check again.confirmtimed out — publishing took longer than 20 minutes. This is not a failed release. The artifacts are staged and the Exit Gate still has them. Do not re-run the release, and do not try to publish the version again: that would burn a version number. Tell the maintainer it is outstanding, and leave it to the hourly Confirm PyPI publication workflow, which finds the release by its pending marker and links it once PyPI catches up. The Exit Gate also emailsa2ui-core-working-group@google.comwith the outcome either way.confirmfailed for another reason — read the log. The publish itself may still have succeeded, so check PyPI before concluding anything.
Open the changelog pull request and get it merged. The release pushed the branch but deliberately did not open the pull request — see "What runs where". Open it yourself:
BRANCH=$(git ls-remote --heads "${REMOTE}" 'release/changelog-*' \ | sed 's#.*refs/heads/##') gh pr create --repo a2ui-project/a2ui --base main --head "$BRANCH" \ --title "chore(release): changelog for ${RELEASED}" \ --body "Moves the \`## Unreleased\` entries under the released versions."Check the diff touches only
CHANGELOG.mdfiles, then ask the maintainer to review it. Do not leave it open: Step 3 blocks the next release until the branch is gone.Report the published versions, the GitHub release links, and the changelog pull request link.
Troubleshooting
could not find any workflows named release-pypi.yml — the workflow is only
dispatchable once it is on main. Check it has merged.
HTTP 403 from Artifact Registry — the Exit Gate allowlists
a2ui-project/a2ui only. This is the expected result on a fork, and not a bug.
On the real repository it means the builder identity no longer matches; see
go/oss-exit-gate-builders.
Permission denied or a failed OIDC exchange — the Exit Gate matches the
workflow path and branch exactly:
github_workflow:a2ui-project/a2ui/.github/workflows/release-pypi.yml@refs/heads/mainRenaming or moving the workflow file breaks releases until the internal config
is updated. It also cannot be triggered from a branch or a tag, only main.
... is already on PyPI — the version was published previously. It cannot be
republished. Work out why the tag series and PyPI disagree before retrying.
One or more packages are not in the project's allowlist or 400 Non-user identities cannot create new projects in Exit Gate logs: a brand-new package name must be added to the OSS Exit Gate allowlist and registered as a Pending Publisher on https://pypi.org/manage/account/publishing/ before its first release. Because PyPI allows only one Pending Publisher at a time for a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com, publish brand-new packages one at a time. See docs/contributing/release/release.md and go/a2ui-release#pypi.
A dry run or failed staging left artifacts behind — the cleanup step runs even on partial failure, but if it was itself skipped, remove the staged version by hand:
gcloud artifacts versions delete "${VERSION}" --package="${PYPI_NAME}" \
--repository=a2ui--pypi --location=us --project=oss-exit-gate-prod --quietRules
- Never edit a version by hand. Versions come from git tags via
hatch-vcs, and the workflow verifies the built artifacts against the version it planned. - Never push tags or run the release scripts locally to publish. The scripts
under
.github/scripts/are safe to run read-only fornotes,next,current,tag, andcheck. Everything else belongs to the workflow. - Never dispatch
dry_run: falsewithout the Step 5 confirmation. - If the maintainer asks to skip the dry run, push back once: it is the only rehearsal before an irreversible publish. Defer if they insist.