Options Directive and Timeouts
You'll learn how to configure pipeline-level settings that control execution behavior, resource management, and automatic cleanup using the options directive.
What Are Pipeline Options?
The options directive lets you set global rules for your entire Jenkins pipeline—like setting a maximum runtime, controlling how many builds to keep, or adding timestamps to console output. Think of it as the "settings menu" for your pipeline's behavior.
These options apply to the whole pipeline (or individual stages) and help you prevent runaway builds, manage disk space, and improve debugging.
Core Options You'll Use
Timeouts
Prevent builds from running indefinitely:
pipeline {
agent any
options {
timeout(time: 1, unit: 'HOURS')
}
stages {
stage('Build') {
steps {
sh 'make build'
}
}
}
}
If your build exceeds one hour, Jenkins automatically aborts it.
Build Retention
Control how many old builds Jenkins keeps:
options {
buildDiscarder(logRotator(numToKeepStr: '10'))
}
This keeps only the last 10 builds, saving disk space.
Timestamps
Add timestamps to every console log line:
options {
timestamps()
}
Makes debugging much easier when you know when each step ran.
Retry Policies
Automatically retry failed builds:
options {
retry(3)
}
Combining Multiple Options
options {
timeout(time: 30, unit: 'MINUTES')
timestamps()
buildDiscarder(logRotator(daysToKeepStr: '7'))
}
Key Takeaway: The options directive configures pipeline-level behaviors like timeouts, build retention, and logging enhancements—preventing resource waste and improving operational control without changing your actual build logic.