# timeout-minutes in GitHub Actions: the default, job against step, what a timeout does

timeout-minutes in GitHub Actions: the 360-minute default, job against step, what a timeout does to the process and the steps after it, and how to pick the number.

By Grant Unwin, published 2026-10-31. Checked against GitHub's documentation on 2026-11-17. The web page: https://www.runners.io/blog/github-actions-timeout-minutes

A job’s `timeout-minutes` defaults to 360, and GitHub-hosted runners stop a job at 6 hours whatever you set. A step may carry its own, up to 360. In our runs, a job that reached its limit ended *cancelled*, and a step that reached its limit *failed* and the job went on to the steps marked `failure()` and `always()`. We ran both on GitHub’s runners and timed what the runner does. Set the number at twice the job’s 95th percentile.

**In short**

- A job's timeout-minutes defaults to 360, GitHub-hosted runners stop a job at 6 hours, and ubuntu-slim stops at 15 minutes.
- In our runs a job that timed out ended cancelled, and a step that timed out ended failed, with the job going on.
- After a job timeout only if: cancelled() and if: always() steps ran; after a step timeout, if: failure() and if: always() steps ran.
- The runner sent SIGINT at the limit, and SIGTERM 7.5 seconds later to a script that ignored it; a child of the step's shell saw neither.
- Set timeout-minutes to twice the job's 95th percentile; the script in the post computes it from your last 100 runs.

This post has the limits, the two behaviours measured, what a hung job bills, and a script that works the number out from your own repository’s last 100 successful runs.

## What are the limits?

| Limit | Figure | Where GitHub says it |
| --- | --- | --- |
| timeout-minutes on a job | Default 360 minutes | Workflow syntax |
| timeout-minutes on a step | No default stated; at most 360 minutes, on hosted and self-hosted runners alike | Workflow syntax |
| Job execution time, any GitHub-hosted runner | 6 hours | Actions limits |
| Job execution time, ubuntu-slim (single CPU) | 15 minutes | GitHub-hosted runners reference |
| Job execution time, self-hosted runner | 5 days | Actions limits |
| A job waiting for a self-hosted runner | Cancelled after 24 hours in the queue | Actions limits |
| The GITHUB\_TOKEN in a job | Expires when the job finishes, or after 24 hours at most | Workflow syntax |
| A job on runners.io | Up to 6 hours, or a shorter maximum your organisation chooses; stopped within a quarter of an hour of it | Our limits page |

GitHub says that if you set `timeout-minutes` above the runner’s own limit, the job is cancelled when the runner’s limit is met instead. The workflow-syntax page gives a default of 360 for a job and no default for a step; a step is bounded by its job unless you give it a number. For a step, GitHub says fractional values are not supported and the value must be a positive integer, so use whole minutes.

Our own limit is the same six hours, or shorter if you choose. A job on runners.io may run for up to 6 hours, an owner or admin can choose a shorter maximum for the organisation, and a job still running at its limit is stopped within a quarter of an hour, as the [limits page](https://www.runners.io/docs/runners/limits) says. So a workflow on our labels that sets nothing is stopped by our limit, at 360 minutes or sooner. A number in the file is still worth having, and the rest of this post is about choosing it. Our per-minute rate for every size, beside GitHub’s, is on the [GitHub Actions runner pricing](https://www.runners.io/pricing) page.

## Job or step: which one do you set?

Set the job’s. It is the one that guarantees the run ends. Set a step’s when one step has a different shape from the rest, such as a deploy that waits on a remote service, or an upload that should not be allowed to eat the whole job’s allowance. The step’s limit is also the one that lets a job recover: a step that times out fails, and the steps after it that you marked with `failure()` or `always()` still run.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 20        # the whole job, twice its p95
    steps:
      - uses: actions/checkout@v7
      - run: npm ci && npm test
      - name: wait for the preview to answer
        timeout-minutes: 3     # this step alone
        run: ./wait-for-preview.sh
      - name: collect logs
        if: failure()          # runs after the step above times out
        run: ./collect-logs.sh
```

## What happens when a job times out?

We wrote a step that never finishes and put `timeout-minutes: 1` on the job or on a step, in five repetitions of each of several variants, on GitHub-hosted `ubuntu-24.04` runners. All 20 runs with the limit on the job ended the same way. GitHub’s limits page says that a job that reaches the 6-hour execution limit “is terminated and fails”, which we did not test. For a limit we set ourselves, the jobs API reported the job as *cancelled*, and so was the step that was running, and the annotations read as below.

| The limit | The job ended | The running step ended | The steps after it | What the run's annotations said |
| --- | --- | --- | --- | --- |
| Job limit of 1 minute | cancelled | cancelled | Skipped. The ones with if: cancelled() and if: always() ran. | Two annotations: The job has exceeded the maximum execution time of 1m0s; The operation was canceled. |
| Step limit of 1 minute | failure | failure | Skipped. The ones with if: failure() and if: always() ran. | The action 'the step that never finishes' has timed out after 1 minutes. |
| Step limit of 1 minute, with continue-on-error: true | success | success | The steps with no condition and with if: success() ran, and so did if: always(). | The action 'the step that never finishes' has timed out after 1 minutes. |

The steps after the one that timed out were five, and each carried a different condition. After a job timeout the one with `if: cancelled()` ran, the one with `if: always()` ran. The ones with no condition, with `if: success()` and with `if: failure()` were skipped. If your cleanup step has no condition, it does not run when the job times out; give it `if: always()`.

## What happens when a step times out?

The step fails, the job goes on, and the conditions behave as they do for any failed step. In all 20 runs with the limit on the step the step ended *failure*, the steps with `if: failure()` and `if: always()` ran, those with no condition, with `if: success()` and with `if: cancelled()` did not, and the job ended *failure*. With `continue-on-error: true` on the same step the job ended *success*: a timeout you have marked as allowed to fail is a green job. We would not use that on anything whose timeout means something is wrong.

## How quickly does the process stop, and what does it see?

The runner does not kill the process at the limit. A script that was the step’s own process received `SIGINT` at the limit. A script that ignored SIGINT then received `SIGTERM` 7.5 seconds later (all 10 runs), and one that ignored both was gone about ten seconds after the limit: its last heartbeat was at 69.4 seconds, and the runner wrote its error line at 70.5. Under a job limit the clock starts at the job, not at the step: with a limit of one minute the first signal arrived 59.4 to 59.8 seconds after the first line of the job’s log. The step began 1.3 to 7.9 seconds after that, so the step itself had run for 51.6 to 58.3 seconds.

| The case | First signal, median | Second signal, median | The process ended |
| --- | --- | --- | --- |
| Job limit, the script is the step's own process, and exits on a signal | SIGINT at 59.5 s | none seen: it had exited | Runner's error line at 60.1 s, both from the job's first log line |
| Job limit, the script ignores SIGINT and SIGTERM | SIGINT at 59.6 s | SIGTERM at 67.1 s | Last heartbeat 67.6 s; error line 68.6 s (from the step start) |
| Step limit, the script is the step's own process, and exits on a signal | SIGINT at 60.0 s | none seen: it had exited | Last heartbeat 59.2 s; error line 60.2 s (from the step start) |
| Step limit, the script ignores SIGINT and SIGTERM | SIGINT at 60.0 s | SIGTERM at 67.5 s | Last heartbeat 69.4 s; error line 70.5 s (from the step start) |
| Job or step limit, the script is a child of the step's shell | no signal seen by its traps | no signal seen by its traps | Error line 72.5 s after the step began (step limit), 72.0 to 72.3 s after the job's first log line (job limit): about 12 s late |

The last row is the one that bites. If your step runs `./build.sh`, the step’s shell runs it as a child. In all 20 of our runs with that arrangement the script’s `trap` handlers never fired, it printed no signal at all, and the runner’s error line came about 12 seconds after the limit. In the runs where the script was the step’s own process, started with `exec`, its traps fired. That is one script on one image, so test yours, but if the script must clean up, make it the step’s own process with `exec ./build.sh`, or put the cleanup in a later step with `if: always()`, which ran in every case we tried.

```yaml
- name: build
  timeout-minutes: 30
  run: exec ./build.sh   # exec: build.sh is the step's process, and in our runs its traps fired
- name: clean up
  if: always()           # runs after a failure, a cancel and a timeout
  run: ./cleanup.sh
```

## What does a hung job bill?

A job that hangs bills until it stops. GitHub rounds each job up to a whole minute and charges its per-minute rate for a private repository, so a job left at the default of 360 minutes costs $2.16 on a Linux 2-core runner, $3.60 on a Windows 2-core runner and $7.92 on a Linux 8-core one. Ten matrix legs that all hang cost ten times that. A job with a timeout of 20 minutes costs $0.12 on the first. GitHub says standard runners in a public repository are free.

## How do you pick the number?

Twice the 95th percentile of the job’s duration over its recent successful runs, rounded up to whole minutes, and never under five. It is a rule of thumb and we state it as one. The p95 leaves a job in one run of twenty slower than the number, which is what the second factor is for. If your job is stable, a factor of 1.5 is defensible; if it depends on a registry or a service, 3 is. What matters more than the factor is that a number exists.

This script reads the last 100 successful runs of a repository through the GitHub CLI and prints, for each job, how many runs it has, its median, its p95 and its longest run in minutes, and the suggested `timeout-minutes`. It makes one API call for the run list and one for each run.

```bash
#!/usr/bin/env bash
# timeout-p95.sh OWNER/REPO [RUNS]
#
# For every job in the last RUNS successful workflow runs of a repository (default 100), print how many runs it
# has, its median, its 95th percentile (nearest rank) and its longest duration, and a suggested timeout-minutes:
# twice the p95, rounded up to whole minutes, and never under 5.
#
# Needs: gh (logged in), jq, awk. It reads the Actions API only, so it works on a private repository you can read.
# It makes one API call for the run list and one for each run, so RUNS=100 is 101 calls of the 5,000 an hour a
# user token gets. A job's duration is completed_at minus started_at: the time it ran, not the time it queued.
set -euo pipefail

repo=${1:?usage: timeout-p95.sh OWNER/REPO [RUNS]}
runs=${2:-100}

durations=$(mktemp)
trap 'rm -f "$durations"' EXIT

run_list=$(gh run list -R "$repo" --status success --limit "$runs" --json databaseId,workflowName \
  --jq '.[] | [.databaseId, .workflowName] | @tsv')

while IFS=$'\t' read -r id workflow; do
  jobs=$(gh api "repos/$repo/actions/runs/$id/jobs?per_page=100") || {
    echo "timeout-p95: could not read the jobs of run $id; stopping, so a partial table is not mistaken for a full one" >&2
    exit 1
  }
  printf '%s\n' "$jobs" | jq -r --arg wf "$workflow" '.jobs[]
    | select(.conclusion == "success" and .started_at != null and .completed_at != null)
    | [$wf, .name, ((.completed_at | fromdate) - (.started_at | fromdate))] | @tsv' >> "$durations"
done <<< "$run_list"

sort -t$'\t' -k1,1 -k2,2 -k3,3n "$durations" |
  awk -F'\t' '
    function flush(   rank, p95, med, sug) {
      if (n == 0) return
      rank = int(0.95 * n); if (rank < 0.95 * n) rank++      # nearest rank: ceil(0.95 * n)
      p95 = d[rank]; med = (n % 2) ? d[(n + 1) / 2] : (d[n / 2] + d[n / 2 + 1]) / 2
      sug = int((2 * p95 + 59) / 60); if (sug < 5) sug = 5
      printf "%-28.28s %-40.40s %4d %7.1f %7.1f %7.1f %6d%s\n", wf, name, n, med / 60, p95 / 60, d[n] / 60, sug, (n < 20 ? "  (under 20 runs: treat the p95 as a guess)" : "")
    }
    BEGIN { printf "%-28s %-40s %4s %7s %7s %7s %6s\n", "workflow", "job", "runs", "median", "p95", "max", "timeout"; printf "%-28s %-40s %4s %7s %7s %7s %6s\n", "", "", "", "(min)", "(min)", "(min)", "(min)" }
    { if ($1 != wf || $2 != name) { flush(); wf = $1; name = $2; n = 0 } d[++n] = $3 }
    END { flush() }'
```

Here is its output for `vitejs/vite`, a public repository, on 17 November 2026. Only 12 of that repository’s last 100 successful runs were of its main CI workflow, so most rows carry the script’s warning that a p95 from fewer than 20 runs is a guess. The row to take from it is the shape: the macOS leg is the slowest the Linux legs need 5 or 6 minutes and the macOS leg 11, and each job gets its own number.

```text
# ./timeout-p95.sh vitejs/vite 100   (run 2026-11-17, bash 5.3.15(1)-release, gh 2.103.3, jq-1.7.1-apple)
workflow                     job                                      runs  median     p95     max timeout
                                                                             (min)   (min)   (min)  (min)
Bot                          AgentScan                                   8     0.2     0.5     0.5      5  (under 20 runs: treat the p95 as a guess)
CI                           Build & Test Passed or Skipped             12     0.1     0.1     0.1      5  (under 20 runs: treat the p95 as a guess)
CI                           Build&Test: node-20, ubuntu-latest         12     2.7     2.9     2.9      6  (under 20 runs: treat the p95 as a guess)
CI                           Build&Test: node-22, ubuntu-latest         12     2.4     2.7     2.7      6  (under 20 runs: treat the p95 as a guess)
CI                           Build&Test: node-24, ubuntu-latest         12     2.0     2.5     2.5      6  (under 20 runs: treat the p95 as a guess)
CI                           Build&Test: node-26, macos-latest          12     4.7     5.1     5.1     11  (under 20 runs: treat the p95 as a guess)
CI                           Build&Test: node-26, ubuntu-latest         12     2.4     2.5     2.5      5  (under 20 runs: treat the p95 as a guess)
CI                           Build&Test: node-26, windows-latest        12     3.5     3.7     3.7      8  (under 20 runs: treat the p95 as a guess)
CI                           Get changed files                          12     0.2     0.3     0.3      5  (under 20 runs: treat the p95 as a guess)
CI                           Lint: node-26, ubuntu-latest               12     1.2     1.5     1.5      5  (under 20 runs: treat the p95 as a guess)
CodeQL                       Analyze (actions)                           7     0.7     0.8     0.8      5  (under 20 runs: treat the p95 as a guess)
Issue Close Require          close-issues                                1     1.1     1.1     1.1      5  (under 20 runs: treat the p95 as a guess)
Lock Closed Issues           action                                      1     0.2     0.2     0.2      5  (under 20 runs: treat the p95 as a guess)
Preview release              preview                                     3     0.4     0.5     0.5      5  (under 20 runs: treat the p95 as a guess)
Publish Package              Detect release commit                       3     0.6     0.6     0.6      5  (under 20 runs: treat the p95 as a guess)
Semantic Pull Request        Semantic Pull Request                      42     0.1     0.2     0.2      5
Semgrep                      Run Semgrep                                 1     1.0     1.0     1.0      5  (under 20 runs: treat the p95 as a guess)
Zizmor                       Run zizmor                                 22     0.3     0.5     0.5      5
```

Read the table against what you know. A job whose p95 is two minutes and whose max is nine is telling you about a slow dependency, and the timeout should sit above the occasional nine and below the six hours. A matrix leg has its own row, because its name carries the matrix values: set the number for the slowest leg. A p95 from before a caching change and one from after it can differ by a lot, so take the last 100 runs only if the job has not changed.

## What we ran

The workflow, the script that never finishes, the collector and the rows are in [studies/G1-timeout](https://github.com/runners-io/ci-measurements/tree/main/studies/G1-timeout). Nine variants ran five times each (45 jobs): the limit on the job or on the step, the script launched as a child of the step’s shell or with `exec`, and a script that exits on a signal or ignores both. The signal times are the script’s own clock; the conclusions come from the jobs API. It is one runner image on one day, and the runner software can change these timings. We did not measure a self-hosted runner, a Windows runner or a job queued behind a concurrency group.

The limits post has [every other quota in one table](https://www.runners.io/blog/github-actions-limits), and the post on [“The operation was canceled”](https://www.runners.io/blog/github-actions-the-operation-was-canceled) covers what a cancellation looks like in a log. The [workflow checker](https://www.runners.io/tools/workflow-check) flags a job with no timeout, and [the guide to making GitHub Actions faster](https://www.runners.io/blog/how-to-make-github-actions-faster) puts timeouts among the cheap changes.

## Sources

- [Workflow syntax for GitHub Actions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax)
- [Actions limits](https://docs.github.com/en/actions/reference/limits)
- [GitHub-hosted runners reference](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)
- [Actions runner pricing](https://docs.github.com/en/billing/reference/actions-runner-pricing)
- [GitHub Actions billing](https://docs.github.com/en/billing/concepts/product-billing/github-actions)
- [ci-measurements, study G1: what a timeout does](https://github.com/runners-io/ci-measurements/tree/main/studies/G1-timeout)

## Frequently asked questions

### What is the default timeout for a GitHub Actions job?

360 minutes, and a GitHub-hosted runner stops any job at 6 hours whatever you set. The single-CPU ubuntu-slim runner stops a job at 15 minutes. A step has no default of its own; its timeout-minutes may be at most 360.

### What is the difference between a job timeout and a step timeout?

In our run a job that reached its limit ended cancelled and ran only its if: cancelled() and if: always() steps. A step that reached its limit failed, and the job went on to run its if: failure() and if: always() steps.

### Does a trap run when a GitHub Actions step times out?

In our runs, only if the script was the step's own process, started with exec. The runner sent SIGINT at the limit, and SIGTERM 7.5 seconds later to a script that ignored it. A child of the step's shell saw no signal and the run ended about 12 seconds late.

### What should timeout-minutes be set to?

Twice the 95th percentile of the job's duration over its recent successful runs, rounded up and never under 5 minutes. That is our rule of thumb, not GitHub's. The script in the post prints it for every job in a repository.
