Mastering GitLab CI Runners: Timeout Configurations You Need to Know
Configuring runners in GitLab CI is crucial for optimizing your CI/CD pipeline. Proper timeout settings prevent long-running jobs from monopolizing resources, ensuring that your CI environment remains responsive and efficient. By setting maximum timeouts, you can avoid scenarios where a single project consumes excessive runner time, impacting overall performance.
To configure a runner's maximum timeout, use the maximum_timeout parameter in the REST API endpoint PUT /runners/:id. Additionally, you can set specific timeouts for script execution using the RUNNER_SCRIPT_TIMEOUT variable and for after_script execution with RUNNER_AFTER_SCRIPT_TIMEOUT. These values must be less than the job timeout to work correctly. For example, if you set a job timeout of 1 hour, you might allow the script to run for 50 minutes, ensuring that it terminates gracefully if it exceeds that limit.
In production, it's vital to remember that misconfigured timeouts can lead to failed jobs and wasted time. Always ensure that your timeout settings align with the expected duration of your jobs. Be cautious with sensitive information; configure runners to only execute jobs on protected branches or tags to prevent exposure. Also, if a registration token is compromised, reset it immediately to maintain security.
Key takeaways
- →Set the `maximum_timeout` parameter to prevent long-running jobs from affecting runner availability.
- →Use `RUNNER_SCRIPT_TIMEOUT` to limit script execution time and avoid resource hogging.
- →Ensure `RUNNER_AFTER_SCRIPT_TIMEOUT` is configured to manage cleanup processes effectively.
- →Always keep timeout values less than the overall job timeout to maintain job integrity.
- →Protect sensitive information by restricting runners to protected branches or tags.
Why it matters
In production, proper runner configuration can significantly reduce job failures and improve resource utilization, leading to faster CI/CD cycles and more reliable deployments.
Code examples
job-with-script-timeouts:variables:RUNNER_SCRIPT_TIMEOUT:15mRUNNER_AFTER_SCRIPT_TIMEOUT:10mscript:-"I am allowed to run for min(15m, remaining job timeout)."after_script:-"I am allowed to run for min(10m, remaining job timeout)."job-artifact-upload-on-timeout:timeout:1h# set job timeout to 1 hourvariables:RUNNER_SCRIPT_TIMEOUT:50m# only allow script to run for 50 minutesscript:-long-running-process > output.txt# will be terminated after 50martifacts:# artifacts will have roughly ~10m to uploadpaths:-output.txtwhen:on_failure# on_failure because script termination after a timeout is treated as a failurejob-with-script-timeouts:timeout:5mvariables:RUNNER_SCRIPT_TIMEOUT:1mRUNNER_AFTER_SCRIPT_TIMEOUT:1mscript:-echo "Starting build..."-sleep 120# Wait 2 minutes to trigger timeout. Script aborts after 1 minute due to RUNNER_SCRIPT_TIMEOUT.-echo "Build finished."after_script:-echo "Starting Clean-up..."-sleep 15# Wait just a few seconds. Runs successfully because it's within RUNNER_AFTER_SCRIPT_TIMEOUT.-echo "Clean-up finished."When NOT to use this
The official docs don't call out specific anti-patterns here. Use your judgment based on your scale and requirements.
Want the complete reference?
Read official docsDeploy any app in seconds — no infrastructure config, no DevOps overhead. Instant deployments from GitHub, built-in databases, and automatic scaling.
Start deploying free →Mastering Environments in GitLab CI/CD: Static vs. Dynamic
Understanding environments in GitLab CI/CD is crucial for effective deployment strategies. Static environments like staging and production are manually created, while dynamic environments are generated on-the-fly for single deployments. This article dives into how to leverage both types effectively.
Maximizing GitLab CI Pipeline Efficiency: Strategies That Work
Pipeline efficiency is crucial for speeding up your CI/CD processes. By analyzing job workloads and leveraging caching, you can significantly reduce pipeline duration. Discover how to optimize your GitLab CI pipelines effectively.
Mastering GitLab CI/CD YAML: Essential Syntax for Production
Get your pipelines running smoothly with GitLab CI/CD YAML syntax. Understand how to leverage global and job keywords to configure your pipeline effectively. This article dives into the specifics that matter in production environments.
Get the daily digest
One email. 5 articles. Every morning.
No spam. Unsubscribe anytime.