You are currently viewing Jenkins pipeline part 5 – options

Jenkins pipeline part 5 – options

Jenkins pipeline part 5 – options

Hello Everyone

Welcome to CloudAffaire and this is Debjeet.

In today’s blog post, we will discuss what are different options available in a Jenkins pipeline.

What is options is Jenkins pipeline?

The options directive allows configuring Pipeline-specific options from within the Pipeline itself. Pipeline provides a number of these options, such as buildDiscarder, but they may also be provided by plugins, such as timestamps.

Similar to pipeline-level options, Jenkins also supports stage-level options. The options directive for a stage is similar to the options directive at the root of the Pipeline. However, the stage-level options can only contain steps like retry, timeout, or timestamps, or Declarative options that are relevant to a stage, like skipDefaultCheckout.

Let’s dig down a bit with some examples.

Jenkins pipeline part 5 – options

Prerequisites

One system with Jenkins installed.

buildDiscarder:

Persist artifacts and console output for the specific number of recent Pipeline runs. For example: options { buildDiscarder(logRotator(numToKeepStr: ‘1’)) }

Parameters for logRotator:

  • daysToKeepStr: history is only kept up to these days.
  • numToKeepStr: only this number of build logs are kept.
  • artifactDaysToKeepStr: artifacts are only kept up to these days.
  • artifactNumToKeepStr: only this number of builds have their artifacts kept.

Create a new pipeline in your Jenkins controller server using below Jenkinsfile. Replace the label as per your Jenkins configuration.

Trigger the pipeline depending on you pipeline setup.

Jenkins pipeline part 5 – options

Since we have set numToKeepStr to one, Jenkins will only maintain logs for one pipeline line run, try to rerun the pipeline and refresh the page.

Jenkins pipeline part 5 – options

checkoutToSubdirectory:

Perform the automatic source control checkout in a subdirectory of the workspace. For example: options { checkoutToSubdirectory(‘foo’) }

Update the pipeline configuration and set to “Pipeline script for SCM” and configure the rest of the settings as per your git remote repository configuration

Jenkins pipeline part 5 – options

Update your Jenkinsfile in remote git repository with below

Trigger the pipeline depending on you pipeline setup.

Observe, Jenkins has cloned your remote repository in your custom directory specified in option directive.

Jenkins pipeline part 5 – options

disableConcurrentBuilds:

Disallow concurrent executions of the Pipeline. By default, Jenkins allow you to rerun the pipeline while existing run InProgress but sometimes you may one to disable any new runs while an existing run InProgress using disableConcurrentBuilds option. For example: options { disableConcurrentBuilds() }

Update the Jenkins file with below and rerun the pipeline. While the pipeline is executing, try to run a new pipeline.

Observe, no new pipeline can get triggered until the current one complete its execution.

Jenkins pipeline part 5 – options

disableResume:

disableResume option do not allow the pipeline to resume if the controller restarts. For example: options { disableResume() }

Update the Jenkins file with below and rerun the pipeline. While the pipeline is executing, try to restart the Jenkins controller.

Observe, pipeline will not get resumed automatically after the controller restart.

newContainerPerStage:

Used with docker or dockerfile top-level agent. When specified, each stage will run in a new container instance on the same node, rather than all stages running in the same container instance.

Update the Jenkins file with below and rerun the pipeline.

Note: You need to setup your Jenkins agent to be able to run your pipeline on a docker container

Jenkins pipeline part 5 – options

Jenkins pipeline part 5 – options

Jenkins pipeline part 5 – options

Observe, the two stages were executed in two different containers using the same image.

overrideIndexTriggers:

Allows overriding default treatment of branch indexing triggers. If branch indexing triggers are disabled at the multibranch or organization label, options { overrideIndexTriggers(true) } will enable them for this job only. Otherwise, options { overrideIndexTriggers(false) } will disable branch indexing triggers for this job only.

This require a multi-branch Jenkins project which is not covered yet, hence just giving the syntax of this option without hands-on.

preserveStashes:

Preserve stashes from completed builds, for use with stage restarting. For example: options { preserveStashes() } to preserve the stashes from the most recent completed build, or options { preserveStashes(buildCount: 5) } to preserve the stashes from the five most recent completed builds.

Update the pipeline definition with below and rerun the pipeline.

Observe, we were successfully able to unstash in stage two, now restart only stage “two”

Jenkins pipeline part 5 – options

Observe, we are still able to unstash in stage two.

Jenkins pipeline part 5 – options

Now remove the option block from the pipeline and rerun the pipeline.

The pipeline will get executed successfully for the first time. Now try to restart stage “two”.

Jenkins pipeline part 5 – options

Jenkins pipeline part 5 – options

Observe, you get an error since stash in stage “one” was not preserved, hence not available in stage “two” when restarted.

quietPeriod:

Set the quiet period, in seconds, for the Pipeline, overriding the global default. For example: options { quietPeriod(30) }

Update the pipeline with Jenkins file hosted in GitHub and trigger is through webhook using below.

Now try to push couple of changes to your GitHub repository in quick succession.

Observe, the pipeline will get triggered for the 1st time and the next trigger will wait till quite period is over.

retry:

On failure, retry the entire Pipeline the specified number of times. For example: options { retry(3) }

Update the pipeline with below and rerun the pipeline.

Jenkins pipeline part 5 – options

Observe, the pipeline will fail as expected but after three retires.

skipStagesAfterUnstable:

Skip stages once the build status has gone to UNSTABLE. For example: options { skipStagesAfterUnstable() }

Update the pipeline definition with below and rerun the pipeline.

Observe, the stage after the unstable stage was skipped and not run.

Jenkins pipeline part 5 – options

Now remove the option block and rerun the pipeline.

Observe, this time the stage after the unstable stage was executed.

Jenkins pipeline part 5 – options

timeout:

Set a timeout period for the Pipeline run, after which Jenkins should abort the Pipeline. For example: options { timeout(time: 1, unit: ‘HOURS’) }

Update the pipeline definition with below and rerun the pipeline.

Observe, the pipeline will get aborted due to timeout.

Jenkins pipeline part 5 – options

parallelsAlwaysFailFast

Set failfast true for all subsequent parallel stages in the pipeline. For example: options { parallelsAlwaysFailFast() }

Update the pipeline definition with below and rerun the pipeline.

Observe, if any stage failed in the parallel stage, all subsequent stage fails.

You can also define options in stage level.

Jenkins stage-level options:

The options directive for a stage is similar to the options directive at the root of the Pipeline. However, the stage-level options can only contain steps like retry, timeout, or timestamps, or Declarative options that are relevant to a stage, like skipDefaultCheckout.

Inside a stage, the steps in the options directive are invoked before entering the agent or checking any when conditions.

Jenkins stage-level options example:

Update the pipeline definition with below and rerun the pipeline.

Observe, the first log running stage was executed successfully but the second long running stage got aborted due to timeout.

Hope you have enjoyed this article, to get more details on Jenkins, please refer below Jenkins official documentation.

https://www.jenkins.io/doc/

Leave a Reply