# Add GitHub Actions CI to a Textual App

Yes. An agent writes a GitHub Actions workflow for your Textual app that runs its Makefile checks, builds the package and smoke-tests the CLI, and opens a PR.

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

## What the agent does

The agent reads what the project already checks locally, because the honest CI for a project with no tests is the set of commands its Makefile already runs. In a terminal app like Textualize/frogmouth, `pyproject.toml` is a Poetry project at version 0.9.2 with `python = "^3.8"`, `textual = "==0.53.1"` pinned exactly, `httpx`, `xdg` and `typing-extensions`, and a dev group of `textual-dev`, `mypy`, `pylint` and `pre-commit`. There is no `tests/` directory and no `.github/` directory. `Makefile` defines `lint` (`pylint frogmouth`), `typecheck` and `stricttypecheck` (`mypy --scripts-are-modules`, the second with `--strict`), `black` and `isort`, `build` (`poetry build`) and `run` (`python -m frogmouth`). `.pre-commit-config.yaml` has a single hook, black 23.3.0, and `.pylintrc` sets a 120-column limit.

Two things in those files shape the workflow. The `black` and `isort` targets call tools that are not in the dev dependencies, so `make black` fails in a fresh `poetry install`; black is only available through pre-commit, which means the format check in CI is `pre-commit run --all-files`, not the Makefile target, and the agent says so rather than adding packages. And `frogmouth/__init__.py` declares `__version__ = "0.9.1"` while `pyproject.toml` says 0.9.2, so the `--version` output the app prints (`frogmouth 0.9.1 (Textual v0.53.1)`) disagrees with the package metadata. The agent adds a small check script that compares the two and fails on mismatch, and reports the current mismatch in the pull request without changing either number, since which one is right is the maintainer's call.

`.github/workflows/ci.yml` runs on `push` to `main` and on `pull_request`, with a matrix of Python 3.8, 3.9, 3.10 and 3.11, the versions the project's classifiers name. Each job checks out, installs Python with `actions/setup-python`, installs Poetry, caches the virtualenv on the lockfile hash, runs `poetry install`, then `make lint` and `make typecheck`, and finally `poetry build`. One job on 3.11 also runs `pre-commit run --all-files` and the version check. `make stricttypecheck` is run once by the agent in the sandbox; if it passes it goes into the workflow, and if it does not the workflow keeps `typecheck` and the pull request lists the strict errors so they can be fixed separately rather than hidden.

A Textual app needs a terminal to run, which a CI job does not have, so the smoke test is the one code path that exits before the UI starts: `poetry run frogmouth --version` and `poetry run python -m frogmouth --version`, both of which argparse answers and exits from in `get_args()` before `MarkdownViewer` is constructed. The agent also installs the built wheel from `dist/` into a clean virtualenv and runs the console script from there, which catches a packaging mistake that `poetry run` would hide. The agent runs the whole sequence in the sandbox on the Python it has, and runs `actionlint` on the workflow file.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add GitHub Actions CI to this Textual application. Read pyproject.toml, poetry.lock, Makefile, .pre-commit-config.yaml, .pylintrc, frogmouth/__init__.py and frogmouth/app/app.py first. Write .github/workflows/ci.yml that runs on push to main and on pull requests, with a matrix of the Python versions the project classifiers list, installs Poetry, caches the virtualenv on the lock hash, runs poetry install, make lint, make typecheck and poetry build, and on one job also runs pre-commit run --all-files and a script that fails if __version__ in frogmouth/__init__.py differs from the version in pyproject.toml. Add a smoke step that runs frogmouth --version through poetry and again from the built wheel installed into a clean virtualenv. Run make stricttypecheck once; include it in the workflow only if it passes, otherwise list its errors in the pull request. Do not add black or isort to the dependencies. Run the full sequence locally and actionlint on the workflow, and open a pull request that reports the version mismatch if there is one without changing either number.",
  "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/ci.yml` and a short version-check script. The description lists the jobs and what each runs, explains why the format check goes through pre-commit instead of `make black`, and states whether `make stricttypecheck` passed and so made it into the workflow or what it reported if not. It names the `__version__` and `pyproject.toml` disagreement with both values and leaves the fix to the maintainer.

The run's record keeps the output of every step the workflow will run, executed once in the sandbox: pylint, mypy, the build, the two `--version` invocations and the wheel install, so a reviewer sees what green will look like before the first workflow run.

Before merging, a reviewer picks which version number is right, decides whether to drop Python 3.8 from the matrix since it has reached end of life upstream even though the project still declares it, and considers adding `pytest-textual-snapshot` tests later so the workflow has something beyond lint and a smoke test to run.

## Run it on every new repository

A maintainer with several Textual tools runs this once per repository from their own server: one `POST /o/{org}/sessions` per repository, 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 rather than opening a second pull request. Each run installs its own Poetry environment in its own sandbox.

Once the workflow exists, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "if this pull request changes pyproject.toml or the version string, confirm the version check still passes and comment with both values if it does not" catches the mismatch before it ships. The trigger adds 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 first workflow for a project with no tests is easy to write and easy to get wrong in ways that only show up on the runner: a Makefile target that calls a tool the lockfile does not install, a strict type check that has never passed, a console app that hangs waiting for a terminal. The agent runs every step first in its own sandbox and writes the workflow from what actually passed, so the first run on GitHub is green or the pull request says exactly why it is not.

Every command's output stays with the run, so a reviewer can read the pylint and mypy results and the `--version` lines rather than wait for the first workflow run to see them. Several tools can be set up at once, each on its own machine with its own record.

## Frequently asked questions

### There are no tests. What does CI actually check?

What the project already checks by hand: pylint, mypy, black through pre-commit, that the package builds, and that the built wheel installs and answers `--version`. That is a real floor for a project with no tests, and the workflow is shaped so a `make test` target slots in when tests arrive.

### Can a Textual app run in CI without a terminal?

Not the UI itself, which is why the smoke test uses `--version`: argparse prints and exits inside `get_args()` before the app object exists. Textual's own testing tools, such as `pytest-textual-snapshot`, run apps headless and are the next step, but they are tests to write, not CI to configure.

### Why not just run make black in the workflow?

Because black is not in the project's dependencies; `make black` only works if you installed it yourself. The one place black is pinned is `.pre-commit-config.yaml`, so `pre-commit run --all-files` is the check that matches what the repository declares. Adding black to the dev group is a reasonable follow-up the agent leaves to the maintainer.

### Will it fix the version mismatch?

No. It reports that `__version__` says 0.9.1 and `pyproject.toml` says 0.9.2 and adds a check so the two cannot drift again, but which is correct depends on what was last published, which only the maintainer knows.

## More Textual jobs

- [Persist User Settings in a Textual App](https://getrush.ai/run/add-persistent-settings/textual/)
- [Add Pre-commit Hooks to a Textual App](https://getrush.ai/run/add-pre-commit-hooks/textual/)
- [Add a Release Workflow for a Textual App](https://getrush.ai/run/add-release-workflow/textual/)

## The same job on other stacks

- [Set Up GitHub Actions CI for a Vapor App](https://getrush.ai/run/add-github-actions-ci/vapor/)
- [Set Up GitHub Actions CI for a VS Code Extension](https://getrush.ai/run/add-github-actions-ci/vscode-extension/)
- [Set Up GitHub Actions CI for an AdonisJS App](https://getrush.ai/run/add-github-actions-ci/adonisjs/)

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