Options directive (timeout, retry) in Jenkins - Step-by-Step Execution

Process Flow - Options directive (timeout, retry)

Start Pipeline

↓

Apply Options Directive

↓

Execute Stage

↓

Check Timeout

↓

Abort Stage

↓

Check Retry Count

↓

Retry Stage

↓

End Pipeline

The pipeline starts, applies options like timeout and retry, runs the stage, checks if timeout occurred to abort, and retries the stage if it fails, until success or retry limit.

Execution Sample

Jenkins

pipeline {
  options {
    timeout(time: 1, unit: 'MINUTES')
    retry(2)
  }
  stages {
    stage('Example') { steps { sh 'exit 1' } }
  }
}

This Jenkins pipeline runs a stage with a 1-minute timeout and retries the stage up to 2 times if it fails.

Process Table

Step	Action	Timeout Check	Retry Count	Stage Result	Next Step
1	Start pipeline and apply options	No timeout	0	Not started	Execute stage
2	Execute stage first time	No timeout	0	Fail (exit 1)	Retry stage (retry=1)
3	Execute stage retry 1	No timeout	1	Fail (exit 1)	Retry stage (retry=2)
4	Execute stage retry 2	No timeout	2	Fail (exit 1)	No retries left, abort
5	Pipeline aborts due to failure after retries	No timeout	2	Aborted	End pipeline

💡 Retries exhausted (2 retries done), stage failed, pipeline aborts

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
retryCount	0	1	2	2	2
stageResult	Not started	Fail	Fail	Fail	Aborted
timeoutReached	No	No	No	No	No

Key Moments - 2 Insights

Why does the pipeline retry the stage after failure?

Because the retry option is set to 2, the pipeline retries the stage up to 2 times after failure, as shown in steps 2, 3, and 4 in the execution table.

What happens if the stage takes longer than the timeout?

If the stage exceeds the timeout, the pipeline aborts the stage immediately. In this example, no timeout occurred, but if it did, step 4 would show 'Timeout reached' and abort.

Visual Quiz - 3 Questions

Look at the execution table, what is the retryCount after the first retry?

A 1

B 0

C 2

D 3

💡 Hint

Check the 'retryCount' variable in the variable_tracker after Step 2 and Step 3.

At which step does the pipeline stop retrying the stage?

A Step 2

B Step 3

C Step 4

D Step 5

💡 Hint

Look at the 'Next Step' column in the execution_table where retries are exhausted.

If the timeout was set to 0.5 minutes, how would the execution table change?

A Timeout Check would be 'Yes' and pipeline aborts earlier

B Retry count would increase

C Stage result would always be success

D No change at all

💡 Hint

Timeout affects the 'Timeout Check' column and can cause early abort as per concept_flow.

Concept Snapshot

Jenkins options directive sets pipeline-wide behaviors.
Use timeout(time, unit) to limit stage duration.
Use retry(count) to rerun failed stages.
If timeout triggers, stage aborts immediately.
Retries stop after count is reached.
Combine for robust pipeline control.

Full Transcript

This visual execution shows how Jenkins pipeline options directive works with timeout and retry. The pipeline starts and applies options. It runs the stage and checks if the timeout is reached. If not, it checks the stage result. On failure, it retries the stage up to the retry count. If retries are exhausted, the pipeline aborts. Variables like retryCount and stageResult track progress. This helps beginners see how timeout stops long stages and retry reruns failed stages automatically.

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