Demo Using Options Directive

In this lesson, you’ll learn how to leverage the options directive to fine-tune your Jenkins Declarative Pipeline. You can apply options globally (pipeline level) or locally (per stage), enabling features like timestamps, retries, and build concurrency control.

Inspecting Available Options

Before configuring your pipeline, explore all supported options in the official Jenkins Pipeline Syntax documentation.

Refer to the Pipeline Syntax documentation for an up-to-date list of directives you can use.

The image shows a webpage from the Jenkins documentation, specifically detailing pipeline syntax options. It includes a navigation menu on the left and descriptions of various pipeline options on the right.

Adding Timestamps to a Stage

Including timestamps in your console log helps you measure step durations and troubleshoot performance issues. To enable timestamps for a specific stage:

pipeline {
    agent any

    stages {
        stage('Install Dependencies') {
            options {
                timestamps()
            }
            steps {
                sh 'npm install --no-audit'
            }
        }
    }
}

Retrying a Stage on Failure

When interacting with external systems (e.g., databases or APIs), transient failures can occur. Use retry(count) to automatically rerun the stage upon failure:

pipeline {
    agent any

    stages {
        stage('Unit Testing') {
            options {
                retry(2)
            }
            steps {
                withCredentials([usernamePassword(
                    credentialsId: 'mongo-db-credentials',
                    passwordVariable: 'MONGO'
                )]) {
                    sh 'npm test'
                }
            }
            post {
                always {
                    junit allowEmptyResults: true,
                          testResults: 'test-results.xml'
                }
            }
        }
    }
}

If your MONGO_URI is missing, Jenkins reports:

MongooseError: The `uri` parameter to `openUri()` must be a string, got `undefined`.

With retry(2), Jenkins will attempt the stage up to two additional times before failing.

The image shows a Jenkins build pipeline for "Build #14" with various stages, including "Checkout SCM," "Tool Install," and "Unit Testing," where the build has failed at the "Unit Testing" stage.

You can track retry attempts in the console output.

Disabling Resume and Concurrent Builds

At the pipeline level, you can:

Prevent resume after a restart using disableResume().
Abort previous builds when a new one starts using disableConcurrentBuilds(abortPrevious: true).

The image shows a Jenkins interface for generating declarative pipeline directives, with options to prevent pipeline resumption and concurrent builds.

pipeline {
    agent any

    environment {
        MONGO_URI = "mongodb+srv://supercluster.d83jj.mongodb.net/superData"
    }

    options {
        disableResume()
        disableConcurrentBuilds(abortPrevious: true)
    }

    stages {
        stage('Install Dependencies') {
            options { timestamps() }
            steps {
                sh 'sleep 100s'
                sh 'npm install --no-audit'
            }
        }
        stage('Dependency Scanning') {
            steps {
                // Security and license checks go here
            }
        }
        stage('Unit Testing') {
            options { retry(2) }
            steps {
                withCredentials([usernamePassword(
                    credentialsId: 'mongo-db-credentials',
                    usernameVariable: 'MONGO_USERNAME',
                    passwordVariable: 'MONGO_PASSWORD'
                )]) {
                    sh 'npm test'
                }
            }
            post {
                always {
                    junit allowEmptyResults: true,
                          testResults: 'test-results.xml'
                }
            }
        }
    }
}

When a new build is triggered during the sleep 100s step, the previous build is aborted:

The image shows a Jenkins pipeline interface for a project named "solar-system," displaying the progress of a build process with steps like "Installing Dependencies" and "Dependency Scanning." The current step is "Installing Dependencies," with several completed tasks and one ongoing task labeled "sleep 100s."

06:57 + sleep 100s
07:25 Sending interrupt signal to process
Superseded by #16
07:29 Terminated: script returned exit code 143

Using disableResume() will remove the ability to resume pipeline execution after a Jenkins restart. Use it only if you have idempotent stages or external state management.

Summary of Pipeline Options

Option	Scope	Description	Example
`timestamps()`	Stage	Prefixes each log line with a timestamp.	`options { timestamps() }`
`retry(count)`	Stage	Retries a failing stage up to `count` times.	`options { retry(2) }`
`disableResume()`	Pipeline	Disables pipeline continuation after a Jenkins restart.	`options { disableResume() }`
`disableConcurrentBuilds(...)`	Pipeline	Prevents concurrent runs; can abort previous builds when triggered.	`options { disableConcurrentBuilds(abortPrevious: true) }`

Links and References

Explore these resources to discover more ways to customize your Jenkins pipelines and streamline your CI/CD workflows.

Introduction and Basics

Jenkins Setup and Interface

Extending Jenkins and Administration

Jenkins Pipelines

Automation and Security

Setting up CI Pipeline

Code Quality and Testing

Containerization and Deployment

Kubernetes and GitOps

AWS Lambda and Advanced Deployment Techniques

Jenkins Administration and Monitoring - Part 1

Shared Libraries in Jenkins

Agents and Nodes in Jenkins

Pipeline Enhancement and Caching

Pipeline Structure and Scripted vs Declarative

Jenkins Administration and Monitoring - Part 2

Backup and Configuration Management

Demo Using Options Directive

Inspecting Available Options

Adding Timestamps to a Stage

Retrying a Stage on Failure

Disabling Resume and Concurrent Builds

Summary of Pipeline Options

Links and References

Watch Video

​Inspecting Available Options

​Adding Timestamps to a Stage

​Retrying a Stage on Failure

​Disabling Resume and Concurrent Builds

​Summary of Pipeline Options

​Links and References

Watch Video

Inspecting Available Options

Adding Timestamps to a Stage

Retrying a Stage on Failure

Disabling Resume and Concurrent Builds

Summary of Pipeline Options

Links and References