All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading