Skip to main content

Documentation Index

Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt

Use this file to discover all available pages before exploring further.

In this lesson, we’ll dive into the Jenkins Build Timeout plugin, which automatically terminates a build when it exceeds a specified duration. Please note this plugin does not apply to Pipeline jobs, as they use their own timeout step.
Pipeline jobs should use the built-in timeout directive. Learn more in the Pipeline Syntax documentation.

​
Plugin Overview

Before configuring any jobs, let’s review the plugin details and installation stats:
The image shows a webpage for the Jenkins "Build Timeout" plugin, detailing its features, version information, and installation statistics. It includes instructions for global configuration and links to related resources.

​
Installation

  1. Go to Manage Jenkins > Manage Plugins.
  2. Search for Build Timeout.
  3. Install and restart Jenkins if prompted.
The image shows a Jenkins interface displaying a list of available plugins, with options to install them. The "Build Timeout" plugin is selected for installation.

​
Configuration Scopes

You can configure timeouts at three levels:
ScopeConfiguration Location
GlobalManage Jenkins > Configure System
Job Build EnvIndividual job’s Build Environment
Build StepAdd build step > Run with timeout

​
1. Global Configuration

Navigate to Manage Jenkins > Configure System and scroll to Global Build Time Out. Enable the plugin and choose a timeout strategy:
StrategyDescription
AbsoluteFixed timeout in minutes (minimum 3 minutes).
ElasticPercentage of recent successful builds.
DeadlineSpecific date/time cutoff (e.g., 2024-12-31 23:59).
The Absolute strategy requires a minimum value of 3 minutes. Values below this will be rejected.
The image shows a Jenkins configuration screen for setting a global build timeout, with options for timeout strategy and actions. The timeout is set to 3 minutes with an option to abort the build if it exceeds this time.
In the same section, define how Jenkins should respond when time runs out:
Post-Timeout ActionDescription
Abort the buildHalt execution and mark as ABORTED.
Fail the buildMark the build as FAILED.
Execute extra build stepsRun custom cleanup or notification steps.
Write a build descriptionAppend timeout details to build metadata.
The image shows a Jenkins configuration screen for managing system settings, specifically focusing on the "Global Build Time Out" settings with options for timeout strategy and duration.
Below is an example using the Absolute strategy with a 3-minute timeout:
The image shows a Jenkins system configuration page with settings for enabling a global timeout strategy, including options for timeout actions and job configuration history.
The image shows a Jenkins configuration screen for setting a global timeout strategy, with options to specify timeout minutes and actions like aborting the build.
With this global property, any job running longer than 3 minutes will be terminated automatically.

​
2. Job-Level Configuration

To apply a timeout to a single job:
  1. Open the job configuration.
  2. In Build Environment, check Terminate the build if it is stuck.
  3. Choose your strategy and set the duration.
The image shows a Jenkins configuration screen for a "sleep-job," focusing on the "Build Environment" settings. Options include terminating a build if it's stuck, with a timeout strategy set to "Absolute" and a timeout of 3 minutes.
You can also reference environment variables for dynamic timeouts if needed: 
def timeoutMinutes = env.BUILD_TIMEOUT ?: 5

​
3. Build-Step Timeout

For fine-grained control, add a Run with timeout wrapper around individual build steps:
  1. Click Add build step.
  2. Select Run with timeout.
  3. Pick Absolute or Deadline, then set your value.
  4. Add subsequent steps based on timeout status.
The image shows a configuration screen from Jenkins, specifically for setting a timeout strategy and build steps for a project. It includes options for selecting a timeout strategy and specifying a project name for copying artifacts.

​
Demonstration

Create a freestyle job named sleep-job with this shell script: 
echo "Started. Sleeping for 300 seconds..."
sleep 300
echo "Finished."
Trigger the build. After 3 minutes, the console will display: 
+ sleep 300
Build timed out (after 3 minutes). Marking the build as aborted.
[build-timeout] Global time out activated
The job stops and is marked ABORTED.

​
Conclusion

You’ve learned how to:
  • Install and overview the Jenkins Build Timeout plugin
  • Configure timeouts globally, per job, or per build step
  • Select strategies: Absolute, Elastic, or Deadline
  • Define post-timeout actions such as aborting, failing, or running cleanup steps
With these techniques, you can keep your Jenkins builds under control and prevent runaway jobs.

​
References

Watch Video