Chapter 21: Jenkins Pipeline and Jenkinsfile

21.12 Options: timeout, retry, timestamps, one build at a time

By Ravindra Bagale · Last updated: 25 October 2026

Why: the problem

A pipeline that works once is not enough. It must also behave well on bad days. Think of Swiggy at lunch time. A test hangs because a network call never returns. Without a timeout, the build waits for hours and blocks others. A flaky npm download fails once in fifty runs. Without retry, a developer loses time for nothing. Two builds start together and both copy to the same live folder. Files get mixed. Without one-build-at-a-time, you get a half new, half old site. The options block fixes all of this in a few lines. In this lesson you will cause each problem on purpose and then fix it with timeout, retry, timestamps and disableConcurrentBuilds, at pipeline level and at stage level.

What we will build

You will make a step hang, a step fail randomly, and two builds overlap. Then you will add timeout, retry, timestamps, disableConcurrentBuilds and quietPeriod, and see the logs change.

What: every term in plain English

• timeout — Stops a build or step after a set time.
• retry — Runs a block again if it fails, up to N times.
• timestamps — Adds the time to each log line.
• disableConcurrentBuilds — Only one build of this job runs at a time.
• abortPrevious — Option of disableConcurrentBuilds that cancels the older build.
• quietPeriod — Waits a few seconds before starting, to batch pushes.
• skipDefaultCheckout — Do not clone automatically.
• Flaky — A step that sometimes fails for no code reason.

How: step by step

1. Make a hang

   sh "sleep 600"
   

   What it does: Simulates a stuck test.

   Output

   (waits)
   

2. Add timeout

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

   What it does: Build aborts after 2 minutes.

   Output

   Timeout has been exceeded
   

3. Make a flaky step

   sh 'test $((RANDOM % 2)) -eq 0'
   

   What it does: Fails half the time.

   Output

   script returned exit code 1
   

4. Add retry

   retry(3) { sh ... }
   

   What it does: Tries up to three times.

   Output

   Retrying
   

5. Overlap two builds

   Click Build Now twice fast
   

   What it does: Two builds run together.

   Output

   #7 and #8 running
   

6. Add one at a time

   options { disableConcurrentBuilds() }
   

   What it does: Second build waits.

   Output

   Waiting for previous build to finish
   

Example 1: Timeout at pipeline and step level

Stack. Jenkins options

Goal. Timeout at pipeline and step level.

Jenkinsfile

pipeline {
  agent any
  options {
    timeout(time: 10, unit: 'MINUTES')
    timestamps()
  }
  stages {
    stage('Slow test') {
      steps {
        timeout(time: 30, unit: 'SECONDS') {
          sh 'echo start; sleep 600; echo never'
        }
      }
    }
  }
}

What each line does

• pipeline timeout 10 min — Safety net for the whole build.
• step timeout 30 s — Tight limit just for the risky step.
• sleep 600 — Our fake hang.
• timestamps — Shows exactly when it was killed.

Green output

11:02:00  + echo start
11:02:00  start
11:02:00  + sleep 600
11:02:30  Cancelling nested steps due to timeout
11:02:30  Sending interrupt signal to process
11:02:30  Timeout has been exceeded
Finished: ABORTED

Expected result. Killed after 30 seconds, not 10 minutes. Times prove it.

Example 2: Retry a flaky download

Stack. Jenkins retry

Goal. Retry a flaky download.

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Install') {
      steps {
        retry(3) {
          sh 'echo try; test $((RANDOM % 2)) -eq 0 && npm ci'
        }
      }
    }
    stage('Whole stage retry') {
      options { retry(2) }
      steps { sh 'npm test' }
    }
  }
}

What each line does

• retry(3) { } — Repeat the block up to 3 times total.
• RANDOM % 2 — Bash random, fails half the time.
• stage options retry — Retry the whole stage.
• Warning — Retry hides real bugs. Use only for network steps.

Green output

+ echo try
try
ERROR: script returned exit code 1
Retrying
+ echo try
try
added 276 packages in 7s
[Pipeline] stage (Whole stage retry)
Tests: 2 passed, 2 total
Finished: SUCCESS

Expected result. The flaky step passed on the second try.

Example 3: One build at a time and quiet period

Stack. Jenkins options

Goal. One build at a time and quiet period.

Jenkinsfile

pipeline {
  agent any
  options {
    disableConcurrentBuilds(abortPrevious: true)
    quietPeriod(10)
    buildDiscarder(logRotator(numToKeepStr: '15', artifactNumToKeepStr: '5'))
  }
  stages {
    stage('Live') {
      steps {
        sh 'sleep 20; mkdir -p "$HOME/lab-live/badge-node"; date | tee "$HOME/lab-live/badge-node/version.txt"'
      }
    }
  }
}

What each line does

• abortPrevious: true — A new build cancels the older running build.
• quietPeriod(10) — Waits 10 seconds so quick pushes become one build.
• artifactNumToKeepStr — Keeps artifacts only for the last 5 builds.
• version.txt — Shows which build wrote last.

Green output

#9  Started by user admin
#10 Started by user admin
#9  Superseded by #10
#9  Finished: NOT_BUILT
#10 Sun Oct 25 11:10:40 IST 2026
#10 Finished: SUCCESS

Expected result. Only the newest build updated Live. No mixed files.

Example 4: Lock a shared lab folder across two different jobs

Stack. Lockable Resources plugin

Goal. Lock a shared lab folder across two different jobs.

Jenkinsfile (both jobs)

pipeline {
  agent any
  stages {
    stage('Live') {
      options { lock(resource: 'lab-live-folder') }
      steps {
        sh 'echo "$JOB_NAME writing"; sleep 15; date | tee "$HOME/lab-live/last-writer.txt"'
      }
    }
  }
}

What each line does

• lock(resource: ...) — From the Lockable Resources plugin. Only one build in the whole Jenkins holds it.
• Two jobs — disableConcurrentBuilds works per job; lock works across jobs.
• Stage level — Only the Live stage waits, tests still run in parallel.
• last-writer.txt — Shows who wrote last.

Green output

badge-scm #20   Lock acquired on [lab-live-folder]
badge-docs #4   Trying to acquire lock on [lab-live-folder]
badge-docs #4   Found 0 available resource(s). Waiting for correct amount: 1.
badge-scm #20   Lock released on resource [lab-live-folder]
badge-docs #4   Lock acquired on [lab-live-folder]
Finished: SUCCESS

Expected result. Two jobs never write the folder at the same time. Use this for one test database or one lab server.

Verify: did it work?

1. Check build queue

   Jenkins home > Build Queue
   

   What it does: Shows waiting builds.

   Output

   badge-scm #11 (pending, waiting for previous)
   

2. See retries

   Pipeline Steps view
   

   What it does: Shows each retry attempt.

   Output

   sh (failed), sh (success)
   

When it is red 1

Timeout has been exceeded

Cause. A step is too slow or stuck.

Fix, step by step

1. Find it with timestamps.
2. Fix the cause, then set a fair limit.

When it is red 2

Retry hides a real test failure

Cause. retry used on tests.

Fix, step by step

1. Remove retry from tests.
2. Fix the flaky test.

When it is red 3

Invalid option type 'disableConcurentBuilds'

Cause. Spelling.

Fix, step by step

1. Copy from the generator.

When it is red 4

No such DSL method 'lock' found

Cause. Lockable Resources plugin is missing.

Fix, step by step

1. Install it.
2. Add the resource name under Manage Jenkins > Lockable Resources, or let Jenkins create it.

Cleanup

1. Remove the hang

   Delete the sleep step and push
   

   What it does: Back to normal.

   Output

   (file saved)
   

2. Clear live

   rm -f $HOME/lab-live/badge-node/version.txt
   

   What it does: Cleans the lab.

   Output

   (no output)
   

Practice tasks

Homework: try at home

Recap

• timeout stops hangs.
• retry only for network steps.
• timestamps help debugging.
• disableConcurrentBuilds protects shared folders.
• quietPeriod batches pushes.

FAQ

Pipeline or step timeout?

Both. A wide pipeline limit and tight step limits.

Does retry wait between tries?

Not by default. Add sleep inside, or use retry(count: 3, conditions: ...) in newer versions.

Does abortPrevious lose work?

The old build stops, which is fine for a deploy that the new build will redo.

Why buildDiscarder?

Old builds fill the controller disk.

What unit options exist?

SECONDS, MINUTES, HOURS.

lock or disableConcurrentBuilds?

disableConcurrentBuilds is for one job. lock protects a thing shared by many jobs.

Interview questions

1. How do you stop stuck builds?

   timeout in options and around risky steps.

2. When to use retry?

   For flaky network actions like downloads, not for tests.

3. How do you stop two deploys at once?

   disableConcurrentBuilds, or lock from the Lockable Resources plugin.

4. How do you save disk on Jenkins?

   buildDiscarder with logRotator.

5. Build aborted after 30 seconds. Why?

   A timeout fired; check timestamps for the slow step.

6. How do you protect a shared test server used by many jobs?

   Use lock from Lockable Resources around the stage that uses it.

7. Why not retry tests?

   Retry hides flaky tests. Fix or quarantine them instead.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards