What the agent does
The agent first lists every job and how long each has a right to run, because a timeout that is too tight is worse than none. In a repository laid out like pallets/click, .github/workflows/ holds six workflows with ten jobs between them and not one timeout-minutes, so each job may hold a runner for GitHub's default of six hours. tests.yaml has a tests job over a nine-entry matrix (CPython 3.10 to 3.14, a free-threaded 3.14t, Windows, macOS and PyPy) that runs uv run --locked --no-default-groups --group dev tox run, and a typing job that runs tox run -e typing with a cached .mypy_cache. pre-commit.yaml has one main job. publish.yaml has build, create-release and publish-pypi, the last gated by a publish environment with id-token: write. lock.yaml runs dessant/lock-threads nightly. nightly.yaml runs race-tests over eleven configurations on two branches, including stress tox envs that run high-iteration race tests with -x, and flask-tests, which checks out pallets/flask and runs its suite against the Click branch. zizmor.yaml runs the workflow linter. Every workflow pins its actions to a commit with a version comment, sets permissions: {} at the top, and has a concurrency group; all of them cancel in-progress runs except nightly.yaml, which sets cancel-in-progress: false.
The agent then measures instead of guessing. It runs the relevant tox envs in its sandbox with time, tox run -e py3.14, -e typing, -e style and -e docs, and reads the repository's recent workflow runs with gh run list --json name,startedAt,updatedAt,conclusion where the installation allows it, so it knows the slowest real duration of each job, including the Windows and macOS entries that take longer than Linux. Each job gets a timeout-minutes of roughly three times its slowest observed run, rounded up to a round number, and the pull request shows the measurement next to every value. The stress jobs in nightly.yaml get the most room, since a race test that hangs is exactly what the timeout exists to catch and exactly what cancel-in-progress: false would otherwise leave running until the next night's run queues behind it. publish-pypi and create-release get short timeouts, because they do one network call each and a hung one blocks the release. lock gets the shortest.
The agent keeps the edits to the one key. Matrices, permissions, concurrency, environment, needs, the pinned action shas and the paths-ignore filters stay as they are, and the key is placed directly under runs-on in every job so the ten diffs read the same. Where a job's slow part is a single step, the uv run ... tox run line in tests.yaml or the gh release create in publish.yaml, it adds a timeout-minutes on that step too, smaller than the job's, so the log says which step stalled. It does not add timeout-minutes to the reusable or composite actions those steps call, because those are owned elsewhere.
To check it, the agent runs actionlint over the six files, runs zizmor the way zizmor.yaml does so the new keys introduce no finding, and confirms with git diff --stat that only the workflow files changed and that each file gained one line per job plus the step lines. It then runs the tests command once more under the new limit in its sandbox to show the limit is not close to the real duration.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add timeout-minutes to every job in the GitHub Actions workflows of this repository. Read every file under .github/workflows and pyproject.toml's tox configuration first, and list each job with what it runs. Measure before you choose values: time the tox environments the jobs run in your sandbox, and read recent run durations with gh run list where you can. Set each job's timeout-minutes to about three times its slowest observed duration, rounded up, with the most room for the nightly stress and race jobs and the least for the release, publish and lock jobs, and add a smaller step-level timeout on the one slow step of a job where there is one. Place the key directly under runs-on. Change nothing else: no matrix, permissions, concurrency, environment or pinned action may move. Run actionlint and zizmor on the result, and open a pull request whose description lists every job, its measured duration and the value you chose.",
"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
The pull request changes the six workflow files and nothing else. Its description is a table with one row per job: the workflow, the job, the command it runs, the slowest duration the agent measured or read from recent runs, and the timeout-minutes it chose, with the stress and race jobs explained separately.
The Tests, pre-commit and zizmor workflows run on the pull request itself, so a reviewer sees the same jobs pass under their new limits, and the zizmor check confirms the linter is still clean. The run's record keeps the actionlint output and the timed tox runs behind each value.
Before merging, a reviewer looks at the nightly values, which are the only ones measured from a schedule rather than a pull request, decides whether the publish jobs should be even tighter, and whether the step-level timeouts are wanted or the job-level ones are enough. The matrices, permissions and pins are untouched.
Run it on every repository with untimed workflow jobs
An organisation with many repositories sends this body once per repository to POST /o/{org}/sessions, each with its own 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 reads its own workflows, so a repository with reusable workflows gets the key on the caller's jobs, and one whose jobs already have a timeout gets only the missing ones.
New workflows drift back without a check, so the pull request also adds a line to the repository's contributing notes, and a webhook_url on the key reports each run.completed with the pull request in result. A run.failed names a repository whose workflow files actionlint rejected before the agent touched them, which is worth knowing on its own.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Ten numbers are easy to type and easy to get wrong: a limit copied from a blog post cancels the macOS matrix entry on a slow day, and a generous one leaves a hung stress job holding a runner all night. The agent times the real commands in its own sandbox, reads the real run history, and writes every value down next to its evidence.
The measurements, the linter output and the diff stay with the run and are pasted into the pull request, so the review is a table to read rather than a guess to second-guess. Dozens of repositories can get the same change at once, each sized from its own history.
Frequently asked questions
Why not one value for every job?
Because the jobs are nothing alike. In this repository a lint job finishes in a minute or two and a stress job is meant to run far longer, so one number is either too tight for the second or useless for the first. The agent measures each job and sizes it alone, and the pull request shows the measurement.
What happens when a job hits its timeout?
GitHub cancels the job, marks it failed, and the log ends with a line naming the step that was running. That is the point: a hung test or a stalled download becomes a visible failure within minutes instead of a runner held for hours, and with step-level timeouts the log names the step itself.
Will this change permissions, pins or the matrix?
No. The agent adds one key per job, directly under runs-on, and one per slow step, and git diff --stat in the pull request shows only those lines. actionlint and zizmor run over the result so a typo in a workflow file cannot slip through.
How does it measure the nightly jobs, which never run on a pull request?
From the repository's recent scheduled runs when gh run list can read them, and from timing the same tox environments in its sandbox otherwise. The pull request marks which values came from which source, so a reviewer knows where to look harder.