What Is a CI Timeout? Explained
A CI timeout is a configured limit that cancels a job or step once it runs longer than allowed, so a hung process cannot tie up a runner forever.
Without timeouts, a single stuck job could hold a runner indefinitely, blocking the queue and burning minutes. Timeouts are a safety valve, but they also surface real problems: a step that times out is either genuinely slow, deadlocked, or waiting on something transient that never arrived.
Why timeouts exist
A timeout bounds how long work can run. It protects shared capacity from a single runaway job, caps wasted spend on a hung process, and gives the pipeline a definite outcome instead of hanging forever. Most CI systems let you set timeouts at the job and step level.
Common causes
- A deadlock or infinite loop that never completes (deterministic).
- A test waiting on an event that never fires (often a race condition).
- A network call hanging because an upstream is slow or unreachable (often transient).
- A genuinely slow step whose limit is simply set too low.
Timeout exit codes
GNU timeout returns 124 when a command exceeds its limit. CI providers may instead report the job as cancelled or timed out. Either way, the signal is the same: the work did not finish in the allotted window.
Transient vs deterministic timeouts
A timeout is deterministic if the step always exceeds the limit (too-tight limit, real deadlock) and transient if it only sometimes does, usually because it was waiting on a slow network or a momentarily overloaded dependency. A retry helps the transient case and wastes time on the deterministic one.
The Latchkey angle
When a timeout traces back to a transient cause Latchkey can recognize, such as a hung network call against a momentarily unreachable registry, the self-healing managed runner can retry so a one-off blip does not fail your build. Timeouts from genuine deadlocks remain yours to fix.
Key takeaways
- A CI timeout cancels work that exceeds its configured limit.
- Timeouts protect shared capacity and cap wasted spend.
- GNU timeout exits 124; providers may report a cancellation.
- A timeout can be transient (slow network) or deterministic (deadlock).