Skip to content
Skills Library
DevOps & cloud · Automation

a2ui-release-python

/a2ui-release-python

Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version.

Repository
a2ui ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version.

Original author description

Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version.

How it works

  1. Step 1: Check environment prerequisites
  2. Step 2: Work out what is being released
  3. Step 3: Preflight locally
  4. Step 4: Dry run
  5. Step 5: Confirm with the maintainer
  6. Step 6: Publish
  7. Step 7: Follow through
  8. Troubleshooting
  9. Rules
Original SKILL.md headings · 440 lines, 3,115 words
SKILL.md preview
---
name: a2ui-release-python
description: Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version.
---

# 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](../../../.github/workflows/release-pypi.yml) 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.md](../../../docs/contributing/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: false` without 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 `plan` is 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.

1. **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.
2. **Python 3.11+.** The script reads `pyproject.toml` with the standard
   library `tomllib`. If your system `python3` is older, run it through the
   project toolchain instead: `uv run python .github/scripts/release_version.py
...`.
3. **GitHub CLI (`gh`)**, installed, authenticated with `github.com`, and with
   write access to `a2ui-project/a2ui`. It dispatches and watches the workflow
   and opens the changelog pull request.
4. **Git identity.** `git config user.name` and `git config user.email` must be
   set, so the changelog commit and pull request pass CLA verification.
5. **A remote that points at `a2ui-project/a2ui`.** It may be called `origin`
   in a direct clone or `upstream` beside a fork; the script finds it by URL.
   The commands below call it `${REMOTE}`:

   ```bash
   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:

```bash
git fetch "${REMOTE}" main --tags
```

```bash
for package in a2ui-core a2ui-agent-sdk a2ui-a2a a2ui-adk; do
  echo "== ${package}"
  python3 .github/scripts/release_version.py notes --package "${package}"
done
```

**Choose 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 `## Unreleased` is 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:

```bash
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 `bump` input, so `build_plan` raises every version by the same
> amount. When the packages warrant different levels — say fixes in
> `a2ui-core` and a feature in `a2ui-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-core` bump may need a pin change first.**
> `a2ui-agent-sdk` declares a range such as `a2ui-core>=0.3.0,<0.4.0` in
> [a2ui_agent/pyproject.toml](../../../python/a2ui_agent/pyproject.toml). If
> the proposed `a2ui-core` version falls outside it, widen the pin in its own
> pull request and **merge it to `main` before dispatching**. The workflow
> releases `main` as 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-a2a` and `a2ui-adk` pin
> `a2ui-agent-sdk` in their `pyproject.toml`, and `a2ui-adk` pins `a2ui-a2a`
> in its `a2a` extra. A new version of a package must fall inside every pin on
> it.

> [!IMPORTANT]
> **A dependent needs its dependencies on PyPI.** Releasing `a2ui-a2a` or
> `a2ui-adk` on its own requires the released `a2ui-agent-sdk` (and, for
> `a2ui-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 a `minor` bump to release `0.1.0`. Before its first
> release, the package name must be added to the OSS Exit Gate allowlist for
> `a2ui/pypi` and registered as a **Pending Publisher** on
> `https://pypi.org/manage/account/publishing/` under the **Google** tab with
> email `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com` and an empty
> subject (see `go/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 from
  `main`, so `python/a2ui_core`, `python/a2ui_agent`, `python/a2ui_a2a` and
  `python/a2ui_adk` must 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:

```bash
# 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.

```bash
gh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \
  -f package="${PACKAGE}" -f bump="${BUMP}" -f dry_run=true
```

Wait a few seconds, then find the run and watch it:

```bash
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:

```bash
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

```bash
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](../../../.github/workflows/release-verify-pypi.yml) 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 `release` goes green, and
> that is normal.** Triggering the Exit Gate is not publishing. The Exit Gate
> works asynchronously and reports only by email, so the `confirm` job sits and
> polls PyPI every 30 seconds for up to 20 minutes waiting for the version to
> appear.
>
> `gh run watch` blocks 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 — while `confirm` is still in progress.

---

## Step 7: Follow through

A release is not done when the workflow goes green.

1. **Confirm the version is live.** The waiting has already happened on the
   runner, so read the `confirm` job's outcome rather than starting a fresh
   wait:

   - **`confirm` succeeded** — the version is on PyPI and the GitHub releases
     have been updated with links. Verify once and move on:

     ```bash
     curl -s -o /dev/null -w '%{http_code}\n' "https://pypi.org/pypi/${PYPI_NAME}/${VERSION}/json"
     ```

     `200` confirms it. A `404` here, after `confirm` reported success, is a CDN
     lag of a minute or two — wait briefly and check again.

   - **`confirm` timed 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](../../../.github/workflows/release-verify-pypi.yml)
     workflow, which finds the release by its pending marker and links it once
     PyPI catches up. The Exit Gate also emails
     `a2ui-core-working-group@google.com` with the outcome either way.

   - **`confirm` failed for another reason** — read the log. The publish itself
     may still have succeeded, so check PyPI before concluding anything.

2. **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:

   ```bash
   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.md` files, then ask the maintainer to
   review it. Do not leave it open: Step 3 blocks the next release until the
   branch is gone.

3. **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/main
```

Renaming 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.md](../../../docs/contributing/release.md#releasing-a-new-package-for-the-first-time) 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:

```bash
gcloud artifacts versions delete "${VERSION}" --package="${PYPI_NAME}" \
  --repository=a2ui--pypi --location=us --project=oss-exit-gate-prod --quiet
```

---

## Rules

- 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 for `notes`, `next`,
  `current`, `tag`, and `check`. Everything else belongs to the workflow.
- Never dispatch `dry_run: false` without 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.

Versions

The database has no other skills named a2ui-release-python.

Database snapshot: 13.11.2026 · package version ce55ee50021f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100release
    Tend release workflow. Use when user asks to "do a release", "release a new version", "cut a release", or wants to publish a new version to PyPI.
  • 100pypi-release
    Release a new seckit version to PyPI from this repository. Use when the user asks to publish, release, ship or tag a new version of seckit, bump the version, or check or fix the PyPI publish workflow.
  • 100release
    Cut a release of pyhubblenetwork — bumps version, generates release notes from commits, commits, tags, and pushes to trigger the PyPI release workflow. Use this skill when the user wants to release, publish, cut a release, bump version, or push a new version to PyPI. Invoke via /release.
  • 86release
    Cut a release of one language's SDK with release-please, tags and release notes. Use when the user asks to release, publish, bump the version or write release notes.
  • 100release
    Cut a new pymobiledevice3 release — create the GitHub release (which publishes to PyPI) with a curated Highlights section. Use when asked to "release vX.Y.Z", "cut a release", or "publish a new version".
  • 100release
    Release a new version of atomic-agents to PyPI and GitHub. Use when the user asks to "release", "publish", "deploy", or "bump version" for atomic-agents.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.