How to add a timeout step to Jenkins Pipeline

Question

When you are using a free style project you can set that after 20 minutes the build is aborted if not concluded. How is this possible with a Jenkins Multi Branch Pipeline Project?

Answer 1

You can use the timeout step:

timeout(20) {
  node {
    sh 'foo'
  }
}

If you need a different TimeUnit than MINUTES, you can supply the unit argument:

timeout(time: 20, unit: 'SECONDS') {

EDIT Aug 2018: Nowadays with the more common declarative pipelines (easily recognized by the top-level pipeline construct), timeouts can also be specified using options on different levels (per overall pipeline or per stage):

pipeline {
  options {
      timeout(time: 1, unit: 'HOURS') 
  }
  stages { .. }
  // ..
}

Still, if you want to apply a timeout to a single step in a declarative pipeline, it can be used as described above.

Answer 2

For a Declarative Pipeline it is adviced to use the timeout step in the options-section.

Executes the code inside the block with a determined time out limit. If the time limit is reached, an exception (org.jenkinsci.plugins.workflow.steps.FlowInterruptedException) is thrown, which leads in aborting the build (unless it is caught and processed somehow). Unit is optional but defaults to minutes.

The timeout-step has 3 parameters you can configure:

• time (required, int)

  • The amount of the timeout, if no unit is stated duration in minutes

• activity (optional, boolean)

  • Timeout after no activity in logs for this block instead of absolute duration.

• unit (optional, values: NANOSECONDS, MICROSECONDS, MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS)

  • The unit for the time, default is MINUTES

Examples:

timeout(time: 10) // would lead to a timeout of 10 minutes (MINUTES is default value)
timeout(time: 10, unit: 'SECONDS') // a 10 seconds timeout
timeout(time: 10, activity: false, unit: 'MILLISECONDS')

The official Jenkins documentation has a very nice example for the use of a timeout:

pipeline {
    agent any
    options {
        timeout(time: 1, unit: 'HOURS') 
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

Answer 3

In a declarative pipeline you can use:

pipeline {
    agent any
    stages {
        stage('Deploy') {
            steps {
                retry(3) {
                    sh './flakey-deploy.sh'
                }

                timeout(time: 3, unit: 'MINUTES') {
                    sh './health-check.sh'
                }
            }
        }
    }
}

Answer 4

For a Declarative Pipeline (timeout for a whole job):

pipeline {
    options {
        timeout(time: 3, unit: 'HOURS')
    }
    
    agent {
        label 'agent_name'
    }
        
    stages {
        stage('Stage_name') {
            steps {
                // ...
            }
        }
    }
    
    // ...
}

For a Scripted Pipeline (timeout for a whole job):

def call() {
    node('agent_name') {
        timeout(time: 3, unit: 'HOURS') {
            stage('Stage_name') {
                // ...
            }
        }
    }    
}

Timeout inside a stage (for a specific action):

Declarative Pipeline

pipeline {
    agent {
        label 'agent_name'
    }

    stages {
        stage('Stage_name') {
            steps {
                timeout(time: 3, unit: 'HOURS') {
                    sh ' ... '
                    echo '...'
                    // ...
                }

                // ...
            }
        }
    }
}

Scripted Pipeline

def call() {
    node('agent_name') {
        stage('Stage_name') {
            timeout(time: 3, unit: 'HOURS') {
                sh '...'
                echo '...'
                // ...
            }

            // ...
        }
    }    
}