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.

Practice

1. What is the main purpose of the timeout option in a Jenkins pipeline?

easy

A. To stop a build if it runs longer than a specified time

B. To retry a failed build step multiple times

C. To schedule a build at a specific time

D. To increase the build's priority in the queue

Solution

1. Step 1: Understand the role of timeout

   The timeout option is used to limit how long a build or step can run.

2. Step 2: Identify the effect of timeout

   If the build runs longer than the set time, Jenkins stops it to save resources.

3. Final Answer:

   To stop a build if it runs longer than a specified time -> Option A

4. Quick Check:

   Timeout = stop long builds [OK]

Hint: Timeout stops builds running too long [OK]

Common Mistakes:

• Confusing timeout with retry
• Thinking timeout schedules builds
• Assuming timeout increases priority

2. Which of the following is the correct syntax to set a retry of 3 times in a Jenkins pipeline options block?

easy

A. options { retry(3); }

B. options { retry 3 }

C. options { retry(3) {} }

D. options { retry(3) }

Solution

1. Step 1: Recall Jenkins options syntax

   The correct syntax uses retry(3) inside the options block without extra braces.

2. Step 2: Identify the valid option

   options { retry(3) } matches the correct syntax exactly: options { retry(3) }.

3. Final Answer:

   options { retry(3) } -> Option D

4. Quick Check:

   Retry syntax = retry(3) inside options [OK]

Hint: Use retry(3) inside options block without extra braces [OK]

Common Mistakes:

• Adding extra braces after retry(3)
• Using retry without parentheses
• Placing retry outside options block

3. Given this Jenkins pipeline snippet:

options {
  timeout(time: 5, unit: 'MINUTES')
  retry(2)
}

stage('Test') {
  steps {
    script {
      def count = 0
      retry(2) {
        count++
        if (count < 3) {
          error('Fail')
        }
      }
      echo "Count is ${count}"
    }
  }
}

What will be the output of the echo command?

medium

A. Count is 1

B. Count is 2

C. Count is 3

D. Build fails before echo

Solution

1. Step 1: Understand retry behavior in script

   The inner retry(2) block retries the enclosed code up to 2 times on failure.

2. Step 2: Trace the count increments and errors

   First run: count=1, error thrown (count<3). Retry 1: count=2, error thrown. Retry 2: count=3, no error, exits retry.

3. Step 3: Determine echo output

   After retries, count is 3, so echo "Count is 3" runs.

4. Final Answer:

   Count is 3 -> Option C

5. Quick Check:

   Retry runs until count=3, then echo prints count [OK]

Hint: Count increments on each retry until no error [OK]

Common Mistakes:

• Assuming retry runs only once
• Thinking count resets on retry
• Ignoring retry inside script block

4. You wrote this Jenkins pipeline options block:

options {
  timeout(10)
  retry(3)
}

But the build fails with a syntax error. What is the problem?

medium

A. timeout requires both time and unit parameters

B. retry cannot be used inside options block

C. timeout value must be a string, not a number

D. retry requires a block after the number

Solution

1. Step 1: Check timeout syntax requirements

   The timeout option requires named parameters: time and unit.

2. Step 2: Identify missing parameters

   Using timeout(10) alone is invalid; it must be timeout(time: 10, unit: 'MINUTES').

3. Final Answer:

   timeout requires both time and unit parameters -> Option A

4. Quick Check:

   Timeout needs time and unit named params [OK]

Hint: Timeout needs time and unit named parameters [OK]

Common Mistakes:

• Passing only a number to timeout
• Thinking retry needs a block
• Confusing timeout value types

5. You want to create a Jenkins pipeline that stops if it runs longer than 2 minutes and retries the entire build up to 2 times if it fails. Which options block correctly implements this?

hard

A. options {
timeout(time: 2, unit: 'MINUTES') {
retry(2)
}
}

B. options {
timeout(time: 2, unit: 'MINUTES')
retry(2)
}

C. options {
timeout(2)
retry(2)
}

D. options {
retry(2)
timeout(2, 'MINUTES')
}

Solution

1. Step 1: Set timeout correctly

   Timeout must use named parameters: time: 2, unit: 'MINUTES'.

2. Step 2: Add retry correctly

   Retry is a separate option inside the options block: retry(2).

3. Step 3: Validate options block structure

   options { timeout(time: 2, unit: 'MINUTES') retry(2) } correctly lists both options without nesting or syntax errors.

4. Final Answer:

   options { timeout(time: 2, unit: 'MINUTES') retry(2) } -> Option B

5. Quick Check:

   Timeout and retry as separate options inside options block [OK]

Hint: Use named params for timeout and separate retry inside options [OK]

Common Mistakes:

• Nesting retry inside timeout block
• Using timeout without named params
• Wrong parameter order or types