# Add a Release Workflow for a Textual App

Yes. An agent adds a tag-triggered workflow to your Textual app that builds with Poetry, publishes to PyPI by trusted publishing, drafts a release, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-release-workflow/textual/). Opens the console with this prompt ready to send, in a Project that has your repository.

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

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

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

- [Add Shell Completion to a Textual App's CLI](https://getrush.ai/run/add-shell-completion/textual/)
- [Add Snapshot Tests to a Textual App](https://getrush.ai/run/add-snapshot-tests/textual/)
- [Add mypy Type Checking to a Textual App](https://getrush.ai/run/add-type-checking/textual/)

## The same job on other stacks

- [Add a Release Workflow With Prebuilt Binaries to a Tokio Server](https://getrush.ai/run/add-release-workflow/tokio/)
- [Add a Release Workflow for a VS Code Extension](https://getrush.ai/run/add-release-workflow/vscode-extension/)
- [Add a Release Workflow for a Chrome Extension](https://getrush.ai/run/add-release-workflow/chrome-extension/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
