# Add timeout-minutes to Every GitHub Actions Job

Yes. An agent adds timeout-minutes to every job in your workflows, sized from how long each really takes, leaves matrices and permissions alone, and opens a PR.

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

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

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

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

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.

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

## More GitHub Actions jobs

- [Set Least-Privilege Permissions on GitHub Actions Workflows](https://getrush.ai/run/add-least-privilege-permissions/github-actions/)
- [Make GitHub Actions Workflows Run in a Merge Queue](https://getrush.ai/run/add-merge-queue-support/github-actions/)
- [Add OpenSSF Scorecard to a Repository with GitHub Actions](https://getrush.ai/run/add-openssf-scorecard/github-actions/)

## The same job on other stacks

- [Add Job Timeouts to a Flask RQ App](https://getrush.ai/run/add-job-timeouts/rq/)

## More jobs like this: Hand off a long task

- [Add a JSON Output Flag to a Cobra CLI](https://getrush.ai/run/add-json-output-flag/cobra/)
- [Add JSON Output to a Go Command-Line Tool](https://getrush.ai/run/add-json-output/go-cli/)

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