What the agent does
The agent starts from how the package is built and versioned, because a release workflow is only that done by a machine. In a project like Textualize/toolong, pyproject.toml declares the toolong package at version 1.5.0 with poetry-core as the build backend, Python ^3.8, click, textual and typing-extensions as dependencies, textual-dev in a dev group and a tl console script pointing at toolong.cli:run. poetry.lock was written by Poetry 1.8. The repository has no .github directory at all, and its tags stop at v1.4.0 while pyproject.toml already says 1.5.0, so a version was bumped without a release ever being cut. That gap is the case the workflow has to make impossible.
.github/workflows/release.yml runs on a pushed tag matching v*. A build job checks out the tag, sets up Python 3.12, installs Poetry on the 1.8 line that wrote the lock file, and before building compares poetry version --short with the tag minus its v, failing with a clear message when they differ, which is the check that would have stopped a v1.5.0 tag from publishing a 1.4.0 wheel or the reverse. It then runs poetry build, installs the wheel into a fresh virtual environment, runs tl --help to prove the console script resolves and imports, and uploads dist/ as an artifact.
A publish job needs the build artifact, runs in a GitHub environment named pypi, holds id-token: write and nothing else, downloads dist/ and calls pypa/gh-action-pypi-publish, which exchanges the workflow's OIDC token for a short-lived PyPI token. No API token is stored in the repository. A release job with contents: write then runs gh release create on the tag with the wheel and sdist attached and generated notes, so the GitHub release and the PyPI release come from one build. The pull request lists the one-time setup a maintainer must do on PyPI: add a trusted publisher for the project naming the owner, the repository, release.yml and the pypi environment, and create that environment in the repository settings with any required reviewers.
Because the repository has no CI, the agent also adds a small ci.yml that runs the same version check and poetry build on pull requests, so a bad pyproject.toml fails before anyone tags. In its sandbox it runs poetry build for real, installs the wheel and runs tl --help, runs the version comparison with the current tag to show it fails the way it should against 1.5.0, and validates both workflow files with actionlint before opening the pull request. A short section in README.md says how to cut a release: bump the version with poetry version, commit, tag v<version>, push the tag.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a release workflow to this Textual app. Read pyproject.toml, poetry.lock, README.md, .gitignore, src/toolong/cli.py and src/toolong/__main__.py first, and list the repository's tags. Write .github/workflows/release.yml that runs on tags matching v*: a build job that installs Poetry on the line that wrote poetry.lock, fails if poetry version --short does not equal the tag without its v, runs poetry build, installs the wheel into a fresh venv and runs tl --help, and uploads dist as an artifact; a publish job in a pypi environment with only id-token write that publishes dist with pypa/gh-action-pypi-publish by trusted publishing and no stored token; and a release job with contents write that creates a GitHub release from the tag with the built files attached and generated notes. Add a ci.yml that runs the version check and poetry build on pull requests. Run poetry build and the smoke test here, show the version check failing against the current tag, validate both files with actionlint, add a release section to the README, and open a pull request that lists the one-time PyPI trusted publisher setup.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that adds .github/workflows/release.yml and .github/workflows/ci.yml and a release section to README.md. The description shows the poetry build output with the wheel and sdist names, the tl --help output from the installed wheel, the version check failing against the current tag because pyproject.toml is ahead of it, and the exact PyPI trusted publisher fields a maintainer fills in once.
The run's record holds the build, the install into a clean environment, the actionlint run and the failing version check, so the first real tag push is the first time the workflow runs on GitHub but not the first time its steps have run.
Before merging, a reviewer decides whether the pypi environment should require a reviewer's approval before publishing, whether to publish to TestPyPI first from a separate environment, and whether to tag 1.5.0 now that the check would pass once the tag exists. The package code and pyproject.toml are unchanged.
Run it on every Python package released by hand
A team with several Textual or other Poetry packages starts one run per repository from its own server: one POST /o/{org}/sessions each, with that repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started instead of a second pull request. Each run reads that package's own build backend and console scripts and writes the smoke test for them.
Once the workflow exists, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request changes the version in pyproject.toml, check that no tag with that version exists yet and that the changelog or release notes mention it, and comment with what is missing" keeps the version bump and the tag from drifting apart again. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A release workflow is the file nobody can test by running it, so the first tag push is usually the first run, on the public index, with a mistake that cannot be unpublished. The agent runs every step it can in its own sandbox, the build, the install, the smoke test and the version check, and validates the YAML, so what the first tag triggers is a sequence that has already run once with the same commands.
The sandbox keeps the build output and the failing check with the run, and the pull request cites them. For a team that maintains several packages, each gets its own run and its own pull request with the one-time setup for that project's name spelled out.
Frequently asked questions
Why trusted publishing rather than a PyPI token in secrets?
A stored token is long-lived, scoped by hand and leaks with the repository's secrets. With trusted publishing, PyPI trusts a specific repository, workflow file and environment, and the publish action trades the job's OIDC token for one that lasts minutes. The repository stores nothing; the pypi environment and id-token: write are the whole credential.
Why check the tag against pyproject.toml?
Because the repository already shows what happens without it: pyproject.toml says 1.5.0 and the latest tag is v1.4.0. Without the check, a tag of v1.5.0 pushed against a commit that still says 1.4.0 would publish a wheel whose version PyPI already has and the upload would fail, or a bumped file would ship under an older tag. One comparison before poetry build ends both.
Why install the wheel and run tl --help?
A build can succeed and still produce a package whose console script points at a module that is not included, which only shows on install. Installing the wheel into a fresh virtual environment and running tl --help exercises the entry point in pyproject.toml and the import of toolong.cli without opening the terminal UI, which needs a TTY the job does not have.
What has to happen outside the pull request?
Two things the agent cannot do: on PyPI, add a trusted publisher for the project naming the GitHub owner, repository, release.yml and the pypi environment; and in the repository settings, create the pypi environment, with reviewers if the team wants an approval step before each publish. The pull request lists both with the exact values.
More Textual jobs
The same job on other stacks
- Add a Release Workflow With Prebuilt Binaries to a Tokio Server (Tokio)
- Add a Release Workflow for a VS Code Extension (VS Code extension)
- Add a Release Workflow for a Chrome Extension (Chrome extension)