Options directive (timeout, retry) in Jenkins - Commands & Configuration

Introduction

Sometimes your Jenkins pipeline steps take too long or fail temporarily. The options directive helps you control how long a step can run and how many times it should retry if it fails.

When a build step might hang or take longer than expected and you want to stop it automatically.

When a flaky test sometimes fails and you want Jenkins to try it again before marking the build as failed.

When you want to limit the total time a pipeline can run to save resources.

When you want to automatically retry a deployment step that might fail due to temporary network issues.

When you want to avoid manual intervention by setting automatic retries and timeouts.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent any
  options {
    timeout(time: 10, unit: 'MINUTES')
  }
  stages {
    stage('Example') {
      steps {
        retry(3) {
          echo 'Running a step with timeout and retry options'
          sh 'sleep 5'
        }
      }
    }
  }
}

The options block sets pipeline-wide behaviors.

• timeout(time: 10, unit: 'MINUTES') stops the pipeline if it runs longer than 10 minutes.
• retry(3) retries the enclosed steps up to 3 times if they fail.

Commands

This command updates the Jenkins job with the new Jenkinsfile containing timeout and retry options.

Terminal

jenkins-jobs --conf jenkins.ini update Jenkinsfile

Expected Output

Job updated successfully

Starts a build of the Jenkins pipeline that uses the timeout and retry options.

Terminal

jenkins-cli build example-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] options

[Pipeline] timeout

Timeout set to 10 minutes

[Pipeline] stage

[Pipeline] { (Example)

[Pipeline] retry

Retry count set to 3

[Pipeline] echo

Running a step with timeout and retry options

[Pipeline] sh

+ sleep 5

[Pipeline] }

[Pipeline] // stage

[Pipeline] End of Pipeline

Finished: SUCCESS

Shows the console output of the last build to verify timeout and retry behavior.

Terminal

jenkins-cli console example-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] options

[Pipeline] timeout

Timeout set to 10 minutes

[Pipeline] stage

[Pipeline] { (Example)

[Pipeline] retry

Retry count set to 3

[Pipeline] echo

Running a step with timeout and retry options

[Pipeline] sh

+ sleep 5

[Pipeline] }

[Pipeline] // stage

[Pipeline] End of Pipeline

Finished: SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: the options directive controls how long your pipeline runs and retry blocks control how many times specific steps retry on failure.

Common Mistakes

Placing the options directive inside a stage instead of at the pipeline level

Options like timeout apply to the whole pipeline or specific steps, but putting them inside a stage block can cause Jenkins to ignore them or behave unexpectedly.

Always place the options directive directly inside the pipeline block, before stages.

Setting retry inside options, misunderstanding it retries the entire pipeline

Retry is not valid inside options and retrying the entire pipeline is not supported this way.

Use retry as a step wrapper around specific steps you want to retry.

Not specifying the unit in timeout, causing Jenkins to default to minutes or fail

Timeout needs a time unit like 'SECONDS', 'MINUTES', or 'HOURS' to work correctly.

Always specify the unit explicitly in the timeout option.

Summary

Use the options directive in Jenkinsfile to set timeout behaviors for your pipeline.

Timeout stops the pipeline if it runs longer than the specified time to save resources.

Use retry blocks around specific steps to automatically rerun them a set number of times if they fail, helping with flaky failures.