GitHub Actions "Your workflow has exceeded the maximum time": how to handle

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

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