Pipeline options
The options directive configures pipeline behavior such as timeouts, retries, and log rotation.
Syntax
options {
timeout(time: 30, unit: 'MINUTES')
buildDiscarder(logRotator(numToKeepStr: '20'))
}The options directive sets pipeline-wide behavior. It goes near the top of the pipeline, after agent.
Useful options
timeout(time: 1, unit: 'HOURS')— abort if it runs too long.retry(3)— retry the pipeline on failure.buildDiscarder(logRotator(numToKeepStr: '10'))— keep only the last 10 builds.disableConcurrentBuilds()— prevent two runs at once.timestamps()— add timestamps to every console line.skipDefaultCheckout()— do not auto-checkout the SCM.
Stage-level options
Some options, like timeout and retry, can also be set on an individual stage.
Example
pipeline {
agent any
options {
timeout(time: 30, unit: 'MINUTES')
buildDiscarder(logRotator(numToKeepStr: '20'))
disableConcurrentBuilds()
timestamps()
}
stages {
stage('Build') {
options { retry(2) }
steps { sh 'make build' }
}
}
}When to use it
- A build with a runaway test uses options { timeout } to abort the pipeline after 30 minutes and free the agent.
- A flaky network fetch step is wrapped in options { retry(3) } at the pipeline level so transient failures auto-recover.
- Log rotation is set in options to keep only the last 20 builds and 60 days of history, preventing disk exhaustion.
More examples
Pipeline timeout and retry
Aborts the pipeline after 30 minutes and retries up to 2 times on failure.
pipeline {
agent any
options {
timeout(time: 30, unit: 'MINUTES')
retry(2)
}
stages {
stage('Build') { steps { sh 'make all' } }
}
}Log rotation with disableConcurrentBuilds
Combines log rotation, concurrent-build prevention, and timestamp injection in the options block.
pipeline {
agent any
options {
buildDiscarder(logRotator(numToKeepStr: '20', daysToKeepStr: '60'))
disableConcurrentBuilds()
timestamps()
}
stages {
stage('Build') { steps { sh 'make' } }
}
}Stage-level retry option
Retries a flaky integration test stage up to 3 times before marking it as failed.
stage('Integration Test') {
options { retry(3) }
steps {
sh './run-integration.sh'
}
}
Discussion