Skip to content



Support of restarting failed stages or steps in a pipeline is limited in Jenkins.

This has been documented in the Jenkins Jira issue JENKINS-33846.

For declarative pipelines there is a solution available which partially addresses this topic:

Nonetheless, still features are missing, so it can't be used in all cases. The more complex Piper pipelines which share a state via commonPipelineEnvironment will for example not work with the standard restart-from-stage.

The step pipelineRestartSteps aims to address this gap and allows individual parts of a pipeline (e.g. a failed deployment) to be restarted.

This is done in a way that the pipeline waits for user input to restart the pipeline in case of a failure. In case this user input is not provided the pipeline stops after a timeout which can be configured.




name mandatory default possible values
script yes
sendMail no true
stepMessage no Do you want to restart?
timeoutInSeconds no 900
  • script - The common script environment of the Jenkinsfile running. Typically the reference to the script calling the pipeline step is provided with the this parameter, as in script: this. This allows the function to access the commonPipelineEnvironment for retrieving, e.g. configuration parameters.
  • sendMail - If it is set to true the step mailSendNotification will be triggered in case of an error.
  • stepMessage - If it is set, the step message can be customized to throw user friendly error messages in Jenkins UI.
  • timeoutInSeconds - Defines the time period where the job waits for input. Default is 15 minutes. Once this time is passed the job enters state FAILED.

Step configuration

We recommend to define values of step parameters via config.yml file.

In following sections of the config.yml the configuration is possible:

parameter general step/stage
sendMail X
stepMessage X
timeoutInSeconds X


Usage of pipeline step:

pipelineRestartSteps (script: this) {
  node {
    //your steps ...


Use node inside the step. If a node exists outside the step context, the input step which is triggered in the process will block a Jenkins executor.

In case you cannot use node inside this step, please choose the parameter timeoutInSeconds carefully!

Side effects



The step depends on the following Jenkins plugins

Transitive dependencies are omitted.

The list might be incomplete.

Consider using the ppiper/jenkins-master docker image. This images comes with preinstalled plugins.