Jenkins: How to set a timeout for a build

Introduction

When you’re working with Continuous Integration and Continuous Delivery (CI/CD) pipelines, managing build times is crucial. Long-running builds can clog up the pipeline, delay feedback, and reduce the overall efficiency of your development process. This is where setting a timeout for Jenkins builds becomes invaluable. In this tutorial, we’ll explore how to effectively set a timeout for Jenkins builds using various methods, from basic to advanced, to ensure your CI/CD pipeline remains efficient and manageable.

Introduction to Build Timeout in Jenkins

Before diving into the methods, let’s understand what a build timeout in Jenkins entails. Essentially, this feature allows you to specify a maximum amount of time a build is allowed to run. If the build exceeds this limit, Jenkins automatically terminates the build, ensuring that resources are freed-up for other tasks and that your pipeline remains unclogged.

Using the Build Timeout Plugin

One straightforward way to implement a build timeout is by using the Build Timeout plugin. Here’s how to do this:

1. First, ensure that the Build Timeout plugin is installed in Jenkins. Navigate to Manage Jenkins > Manage Plugins, and check the Available tab for Build Timeout. Install it if it’s not already done.
2. Next, go to your job’s configuration page by choosing your job and clicking on Configure.
3. Scroll down to the Build Environment section, and you’ll see the Build Timeout option. Check the box to enable it.
4. Choose the timeout strategy that suits your needs. You might want to set an absolute timeout, or perhaps a timeout based on the build’s output. Configure the settings as required.
5. Save your changes, and you’re all set. The next time you run your job, it will automatically terminate if it exceeds the specified timeout period.

Setting a Timeout Script in a Pipeline Job

While the Build Timeout plugin offers a simple and effective way to manage build durations, Jenkins Pipeline provides more flexibility. You can write a declarative pipeline script with a timeout block. Here’s how:

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        timeout(time: 20, unit: 'MINUTES') {
          echo 'Running build...';
        }
      }
    }
  }
}

This script sets a 20-minute timeout for the build stage. If the build takes longer than 20 minutes, Jenkins will cancel the build.

Implementing Dynamic Timeouts

In certain cases, you might need the build timeout to be dynamic, based on certain conditions. For example, different branches might require different timeout thresholds. Here’s how to implement a dynamic timeout in a Jenkinsfile:

pipeline {
  agent any
  parameters {
    string(
      name: 'BRANCH_NAME',
      defaultValue: 'main',
      description: 'Branch name'
    )
  }
  stages {
    stage('Build') {
      steps {
        script {
          def timeoutDuration = (BRANCH_NAME == 'main') ? 30 : 15
          timeout(time: timeoutDuration, unit: 'MINUTES') {
            echo 'Running build for ' + BRANCH_NAME + ' branch...';
          }
        }
      }
    }
  }
}

This example adjusts the timeout based on the branch name. Main branch builds are allowed 30 minutes, while all other branches have a 15-minute limit.

Using Environment Variables to Set Timeouts

Another advanced method for setting build timeouts involves using environment variables. This approach allows you to modify the timeout without changing the job configuration or Jenkinsfile script. For instance:

pipeline {
  agent any
  environment {
    TIMEOUT = '20'
  }
  stages {
    stage('Build') {
      steps {
        timeout(time: env.TIMEOUT.toInteger(), unit: 'MINUTES') {
          echo 'Environment-based timeout set to ' + TIMEOUT + ' minutes.';
        }
      }
    }
  }
}

This script uses an environment variable TIMEOUT to determine the duration of the build timeout. You can easily change this value in the job’s environment settings rather than modifying the pipeline script.

Conclusion

Setting timeouts for Jenkins builds is a fundamental aspect of managing a smooth and efficient CI/CD pipeline. Whether you’re using the Build Timeout plugin for a straightforward setup or delving into more dynamic and flexible timeout configurations with Jenkins Pipeline, each method has its advantages. Understanding and applying these strategies ensures your builds don’t hang indefinitely, conserves resources, and maintains the velocity of your development process.