Options directive (timeout, retry) in Jenkins - Mini Project: Build & Apply

Using Jenkins Options Directive with Timeout and Retry

📖 Scenario: You are setting up a Jenkins pipeline to build a simple project. Sometimes the build step can take too long or fail temporarily. To handle this, you want to add controls to stop the build if it takes too long and retry the build if it fails.

🎯 Goal: Build a Jenkins pipeline script that uses the options directive to set a timeout of 5 minutes and retry the build step 2 times if it fails.

📋 What You'll Learn

Create a Jenkins pipeline with a pipeline block

Add an options directive with timeout set to 5 minutes

Add retry directive to retry the build step 2 times

Include a simple sh step that simulates a build command

Print a message when the build starts

💡 Why This Matters

🌍 Real World

In real projects, builds can hang or fail temporarily. Using timeout and retry helps keep pipelines reliable and efficient.

💼 Career

DevOps engineers often configure Jenkins pipelines with options like timeout and retry to improve automation robustness.

1

Create the basic Jenkins pipeline structure

Create a Jenkins pipeline script with a pipeline block and a stages section containing one stage named Build. Inside the Build stage, add a steps block with a shell command echo "Starting build".

Jenkins

pipeline {
    // Define the pipeline
    // Your code here
}

Hint

Start with pipeline {} and add stages with one stage('Build'). Use sh 'echo "Starting build"' inside steps.

2

Add the options directive with timeout

Inside the pipeline block, add an options directive that sets a timeout of 5 minutes using timeout(time: 5, unit: 'MINUTES').

Jenkins

pipeline {
    // Add options directive with timeout here
    stages {
        stage('Build') {
            steps {
                sh 'echo "Starting build"'
            }
        }
    }
}

Hint

Use options { timeout(time: 5, unit: 'MINUTES') } inside the pipeline block but outside stages.

3

Add retry logic to the build step

Inside the steps block of the Build stage, wrap the sh command with a retry(2) block to retry the build step 2 times if it fails.

Jenkins

pipeline {
    options {
        timeout(time: 5, unit: 'MINUTES')
    }
    stages {
        stage('Build') {
            steps {
                // Add retry block here
            }
        }
    }
}

Hint

Wrap the sh command inside retry(2) { ... } to retry twice on failure.

4

Print a message to confirm pipeline setup

Add a post section inside the pipeline block with an always block that prints echo 'Pipeline finished' after the pipeline runs.

Jenkins

pipeline {
    options {
        timeout(time: 5, unit: 'MINUTES')
    }
    stages {
        stage('Build') {
            steps {
                retry(2) {
                    sh 'echo "Starting build"'
                }
            }
        }
    }
    // Add post section here
}

Hint

Use post { always { echo 'Pipeline finished' } } inside the pipeline block to print after the run.

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