What does timeout-minutes do in a GitHub Actions job, and what is its default?

## What the key does `timeout-minutes` is a ceiling on wall-clock execution. It appears in two places: ``` jobs: test: runs-on: ubuntu-latest timeout-minutes: 20 steps: - uses: actions/checkout@v4 - name: Integration tests timeout-minutes: 12 run: ./gradlew integrationTest ``` At **job** level it limits the whole job. At **step** level it limits that one step. When the limit is reached the work is terminated and the result is a **failure** — not a skip, not a retry, and nothing is automatically re-run. ## The default that surprises people The job-level default is **360 minutes**. Six hours. Almost no CI job legitimately needs that, and the default exists to accommodate the rare long build rather than to describe a typical one. The consequence is the reason this question gets asked. A test that deadlocks, a script that waits forever on a prompt, a `docker compose` health check that never goes healthy — none of these fail. They hang, holding a runner. On GitHub-hosted runners you pay for that time; on self-hosted runners you starve every other job in the queue behind it. A job that would normally finish in four minutes sitting at three hours is not a mystery, it is the default doing exactly what it was configured to do. There is also a platform limit behind the setting: on GitHub-hosted runners each job is capped at six hours of execution regardless of what you write, so raising `timeout-minutes` above 360 does not extend a hosted job. ## Job level or step level? Use **step level** when one specific operation is the plausible hang and you want everything after it to still happen. Because a timed-out step fails, the steps after it are skipped unless they carry `if: always()` or `if: !cancelled()` — so the useful pattern is a bounded risky step plus unconditional diagnostics and teardown: ``` - name: Integration tests timeout-minutes: 12 run: ./gradlew integrationTest - name: Logs if: failure() run: docker compose logs --no-color > compose.log - name: Tear down if: always() run: docker compose down -v ``` Use **job level** as the backstop for everything the step-level bounds do not cover — setup, cache restore, an action that hangs. A job-level timeout ends the job outright, which means teardown steps do not get a chance to run; that is a real limitation and the reason the step-level bound is the more surgical instrument. Most mature pipelines use both: a generous job-level cap that is still far below six hours, and tight caps on the two or three steps known to be able to hang. ## How to pick a number Look at the job's actual duration over recent runs and set the timeout well above the slow tail but far below "nobody will notice". A common rule of thumb is roughly two to three times the observed p95 — enough headroom that a cold cache or a slow runner does not produce a false red, tight enough that a hang is caught in minutes. Revisit it when the job grows; a timeout that starts firing on healthy runs is worse than no timeout, because the team learns to re-run red builds reflexively. ## What it is not It is not a queue-time limit. Time spent waiting for a runner is not execution, and `timeout-minutes` does not start counting until the job begins running. It is not cancellation-safe cleanup. A timed-out job is over; only step-level timeouts leave room for the remaining steps to react. It is not a retry mechanism. If a job's flakiness needs bounded retries, that is a separate decision about re-running the job, and a timeout only turns an infinite hang into a definite failure so that such a decision is possible at all.