Job Retry and Timeout
You'll learn how to make your GitLab CI/CD pipelines more resilient by automatically retrying flaky jobs and preventing them from running indefinitely.
Why Retry and Timeout Matter
Sometimes jobs fail due to temporary issues—a network hiccup, a flaky test, or a brief service outage. Instead of forcing developers to manually re-run pipelines, GitLab can automatically retry failed jobs. Similarly, some jobs might hang or run far longer than expected, wasting runner resources. Timeouts protect you from these runaway jobs.
Think of it like a vending machine: if your snack gets stuck, the machine might shake it loose automatically (retry). But if something's truly broken, the machine won't keep trying forever (timeout).
Configuring Retry
Use the retry keyword in your job definition:
test_job:
script:
- npm test
retry: 2 # Retry up to 2 times (3 total attempts)
You can also specify conditions:
integration_test:
script:
- ./run_integration_tests.sh
retry:
max: 2
when:
- runner_system_failure
- stuck_or_timeout_failure
Setting Timeouts
Prevent jobs from running too long with timeout:
long_build:
script:
- make build
timeout: 1h # Kill job after 1 hour
Valid formats: 30s, 5m, 2h, 1d.
Practical Use Cases
- Retry: Flaky integration tests, network-dependent operations, external API calls
- Timeout: Builds that shouldn't exceed known duration, preventing infinite loops or stuck processes
Key Takeaway: Use retry to handle transient failures automatically and timeout to prevent jobs from consuming resources indefinitely—making your pipelines both more reliable and more efficient.