Index of every page on this site: llms.txt
All skills
a2ui-project avatar

/a2ui-release-python

@6bf4cc2
by A2UIa2ui-project/a2ui18k stars
1,430
Run it yourself

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.

  • 1 file
  • 21.6 KB
  • Updated 2 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/a2ui-project/a2ui/a2ui-release-python

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈86 tokens for metadata: the name and description. ≈5.4k when used: this file.

Description uses 4.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈346 characters, or 4.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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: 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}:

    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 --tags
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:

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. If the proposed a2ui-core version falls outside it, widen the pin in its own pull request and merge it to main before dispatching. When doing so, also update tool.hatch.version.fallback-version in the dependency's pyproject.toml (and any co-released packages) so tagless checkouts and shallow CI clones (fetch-depth: 1) satisfy the new constraint. 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:

# 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=true

Wait 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 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:

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

    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/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 --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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 6bf4cc2. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago
metadata
{
  "internal": true
}

README badge

README badge for a2ui-project/a2ui/a2ui-release-python