## TL;DR
GitHub kills jobs at the timeout (default 6 hours, configurable down, not up beyond the max). If your job legitimately needs longer, it does not belong in Actions: split it, move it to a self-hosted long runner, or run it elsewhere. If it should not take that long, the timeout is telling you the job hangs: find the hang instead of raising the limit.

## The query
```text
GitHub Actions "Your workflow has exceeded the maximum time": how to handle
```

## Use this when
- Jobs are killed at the execution time limit
- Long builds, tests, or migrations cannot finish
- Deciding whether to split or move the workload
- Timeout configuration questions

## Not for when
- Jobs that hang indefinitely (debug the hang)
- Step-level timeouts (different setting)
- Self-hosted runner capacity

## Steps

### Step 1: Determine: too slow or actually hung
Check the job logs at the kill time: was it making progress or stuck on one step for hours. Progress means the workload is too big; stuck means a hang (waiting on input, deadlocked test, network stall).
Expected output: classified as legitimate-long vs hung.

### Step 2: For hung jobs, find the stall
Look at the last log lines before the timeout: the step that produced no output for hours is the hang. Common causes: interactive prompts in CI, tests waiting on unavailable services, artifact uploads stalled on network.
Expected output: the hanging step identified and fixed.

### Step 3: For legitimate-long jobs, split the work
Break the job into parallel matrix jobs or sequential jobs with artifacts between them. Each job gets its own timeout budget; the total work can exceed any single job's limit.
Expected output: the workload completing within per-job limits.

### Step 4: Set explicit timeouts per job
Set timeout-minutes on every job to fail fast instead of burning 6 hours. A job that should take 20 minutes gets a 30-minute timeout; the 6-hour default is for catching hangs, not for planning.
Expected output: runaway jobs fail in minutes, not hours.

### Step 5: Move truly long workloads off Actions
Multi-hour builds, migrations, and data jobs belong on dedicated infrastructure, not CI. Actions is for CI; long batch work needs a batch system.
Expected output: the workload running where long runtimes are normal.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dJc3HPxlnuQO2F7nCTy76A