Pipeline (jenkins-library 1.4.0 API)

jenkins_shared_library.pipelines.base.Pipeline

This class represents a basic Jenkins pipeline. Use the methods of this class to add stages to your pipeline.
Required Plugins:
The following plugins are required:
Setup:
- Create a Multibranch Pipeline or Pipeline job for your project. Any other type of build will fail.
Example:
```
 @Library('fill this out according to your setup') import org.zowe.jenkins_shared_library.pipelines.base.Pipeline

 node('pipeline-node') {
   Pipeline pipeline = new Pipeline(this)

   // Set your config up before calling setup
   pipeline.admins.add("userid1", "userid2", "userid3")

   // update branches settings if we have different settings from #defineDefaultBranches()
   pipeline.branches.addMap([
     [
       name         : 'lts-incremental',
       isProtected  : true,
       buildHistory : 20,
     ]
   ])

   // MUST BE CALLED FIRST
   pipeline.setup()

   // Create a stage in your pipeline
   pipeline.createStage(name: 'Some Pipeline Stage', stage: {
       echo "This is my stage"
   })

   // MUST BE CALLED LAST
   pipeline.end()
 }
 
```
In the above example, the stages will run on a node labeled 'pipeline-node'. You must define the node where your pipeline will execute.

Stages are not executed until the end method is called. This means that you can't rely on stages being executed as soon as they are defined. If you need logic to help determine if a stage should be executed, you must use the proper options allowed by org.zowe.jenkins_shared_library.pipelines.base.arguments.StageArguments.
Note:
Due to issues with how Jenkins loads a shared pipeline library, you might notice that some methods that were meant to be overridden by subclasses are just named differently. This is due to how the CPS Jenkins wrapper modifies classes and subclasses. See below for the full explanation of the problem.
- The superclass implements a method of the signature setup()
- The subclass implements a method of the signature setup(). Which is the same as the superclass, so under normal OOP the method would be overridden.
- In the subclass's implementation of setup(), it calls super.setup().
  - In normal Groovy OOP, this would be fine and the superclass method will be called properly.
  - In Jenkins, calling super.setup() actually calls the subclass method. this results in a stack overflow error, since the method is just calling itself until the method stack is completely used up.
I believe this is due to how Jenkins does inheritance. It looks like Jenkins is just taking all the methods available across the superclasses of a class and adding them as a base definition to the class itself. When there's a conflict, it seems that Jenkins just takes the method from the lowest class in the hierarchy and refers all calls to that method no matter what. This theory stems from the fact that if you call a superclass method that accesses a superclass private variable, Jenkins complains that the variable doesn't exist. If you change that variable or method to protected or public, Jenkins doesn't complain anymore and operation acts as normal.

This issue seems to signify that they may never fix this problem.
See Also:
behavior.CPSGrandchild
behavior.NonCPSGrandchild

Field Summary

Fields
Modifiers	Name	Description
`protected static java.lang.String`	`_SETUP_STAGE_NAME`	The name of the setup stage.
`protected PipelineControl`	`_control`	This control variable represents internal states of items in the pipeline.
`protected org.zowe.jenkins_shared_library.email.Email`	`_email`	An Email instance to handle email related functions
`protected boolean`	`_isProtectedBranch`	Tracks if the current branch is protected.
`protected boolean`	`_shouldSkipRemainingStages`	Tracks if the remaining stages should be skipped.
`protected Stages`	`_stages`	The stages of the pipeline to execute.

Properties Summary

Properties
Type	Name and description
`PipelineAdmins`	`admins` This is a list of administrator ids that will receive notifications when a build happens on a protected branch.
`java.lang.String`	`baseDirectory` Base directory of the project.
`Branches<org.zowe.jenkins_shared_library.pipelines.base.models.Branch>`	`branches` A map of branches.
`java.util.List`	`buildOptions` Options that are to be added to the build.
`java.util.List`	`buildParameters` Build parameters that will be defined to the build
`java.util.List<java.lang.String>`	`buildUpstreams` Upstream builds
`java.lang.String`	`packageName` Package name of the project
`java.lang.Object`	`steps` Reference to the groovy pipeline variable.
`java.lang.String`	`version` Package current semantic version in {@code <major>.

Constructor Summary

Constructors
Constructor and description
`Pipeline (java.lang.Object steps)` Constructs the class.

Methods Summary

Methods
Type Params	Return Type	Name and description
	`protected void`	`_closureWrapper(Stage stage, groovy.lang.Closure closure)` Wraps a closure function in a try catch.
	`protected static java.lang.String`	`_getStageSkipOption(Stage stage)` Gets the stage skip parameter name.
	`protected void`	`_sendEmailNotification()` Send an email notification about the result of the build to the appropriate users
	`void`	`addBuildOption(java.lang.Object option)` Add new build options to the pipeline.
	`void`	`addBuildParameter(java.lang.Object param)` Add new build parameter to the pipeline
	`void`	`addBuildParameters(java.util.List params)` Add new build parameters to the pipeline
	`void`	`addBuildParameters(org.jenkinsci.plugins.structs.describable.UninstantiatedDescribable... params)` Add new build parameters to the pipeline.
	`void`	`addUpstreams(java.lang.String... upstreams)` Define upstreams of the pipeline.
	`Stage`	`createStage(StageArguments args)` Creates a new stage to be run in the Jenkins pipeline.
	`Stage`	`createStage(java.util.Map arguments)` Creates a new stage to be run in the Jenkins pipeline.
	`protected void`	`defineDefaultBranches()` Setup default branch settings
	`protected void`	`end(EndArguments args)` Pseudo end method, should be overridden by inherited classes
	`protected void`	`end(java.util.Map args = [:])` Pseudo end method, should be overridden by inherited classes
	`void`	`endBase(EndArguments args)` Signal that no more stages will be added and begin pipeline execution.
	`void`	`endBase(java.util.Map arguments = [:])` Signal that no more stages will be added and begin pipeline execution.
	`Stage`	`getFirstFailingStage()` Gets the first failing stage within _stages
	`Stage`	`getStage(java.lang.String stageName)` Get a stage from the available stages by name.
	`void`	`setResult(ResultEnum result)` Set the build result
	`protected void`	`setup(SetupStageArguments arguments)` Pseudo setup method, should be overridden by inherited classes
	`protected void`	`setup(java.util.Map arguments = [:])` Pseudo setup method, should be overridden by inherited classes
	`void`	`setupBase(SetupStageArguments arguments)` Initialize the pipeline.
	`void`	`setupBase(java.util.Map arguments = [:])` Initialize the pipeline.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class java.lang.Object`	`java.lang.Object#wait(long, int), java.lang.Object#wait(long), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- Field Detail
  - protected static final java.lang.String _SETUP_STAGE_NAME
    
    The name of the setup stage.
    Default:
    "Setup".
  - protected PipelineControl _control
    
    This control variable represents internal states of items in the pipeline.
  - protected final org.zowe.jenkins_shared_library.email.Email _email
    
    An Email instance to handle email related functions
  - protected boolean _isProtectedBranch
    
    Tracks if the current branch is protected.
  - protected boolean _shouldSkipRemainingStages
    
    Tracks if the remaining stages should be skipped.
  - protected final Stages _stages
    
    The stages of the pipeline to execute. As stages are created, they are added into this control class.
- Property Detail
  - final PipelineAdmins admins
    
    This is a list of administrator ids that will receive notifications when a build happens on a protected branch.
  - java.lang.String baseDirectory
    
    Base directory of the project.
    By assigning a value to baseDirectory, many built-in stages will be wrapped with
```
dir(baseDirectory) {}
```
    .
  - Branches<org.zowe.jenkins_shared_library.pipelines.base.models.Branch> branches
    
    A map of branches.
  - java.util.List buildOptions
    
    Options that are to be added to the build.
  - java.util.List buildParameters
    
    Build parameters that will be defined to the build
  - java.util.List<java.lang.String> buildUpstreams
    
    Upstream builds
  - java.lang.String packageName
    
    Package name of the project
    Note:
    This property could be used for different purpose based on pipeline. For GenericPipeline, this property is used to generate artifact publishing path in the artifactory. If we have package name of org.zowe.my-project, the artifacts generated by this project will be placed into <repo>/org/zowe/my-project/ folder.
    
    See Also:
    GenericPipeline.getBuildStringMacros
  - java.lang.Object steps
    
    Reference to the groovy pipeline variable.
    See Also:
    Pipeline(def)
  - java.lang.String version
    
    Package current semantic version in <major>.<minor>.<patch> format.
    Note:
    This version should NOT have "v" prefix, and should NOT have pre-release string and metadata.
- Constructor Detail
  - Pipeline(java.lang.Object steps)
    
    Constructs the class.
    When invoking from a Jenkins pipeline script, the Pipeline must be passed the current environment of the Jenkinsfile to have access to the steps.
    Example:
    def pipeline = new Pipeline(this)
    Parameters:
    steps - The workflow steps object provided by the Jenkins pipeline
- Method Detail
  - protected final void _closureWrapper(Stage stage, groovy.lang.Closure closure)
    
    Wraps a closure function in a try catch.
    Used internally by createStage(StageArguments) to handle errors thrown by timeouts and stage executions.
    
    Parameters:
    stage - The stage that is currently executing
    closure - The closure function to execute
  - protected static java.lang.String _getStageSkipOption(Stage stage)
    
    Gets the stage skip parameter name.
    Parameters:
    stage - The stage to skip.
    Returns:
    The name of the skip stage parameter.
  - protected void _sendEmailNotification()
    
    Send an email notification about the result of the build to the appropriate users
  - void addBuildOption(java.lang.Object option)
    
    Add new build options to the pipeline.
    If you need custome build options, you can use this method to notify pipeline.
    Note:
    Use properties() directly in your pipeline will not work because the library may oeverwrite your settings.
    Example:
    You want to define thottle for your pipeline:
    def thottle = [ $class : 'JobPropertyImpl', throttle : [ count : 1, durationName : 'hour', userBoost : true ] ] pipeline.addBuildOption(thottle)
    Parameters:
    option - build option
  - void addBuildParameter(java.lang.Object param)
    
    Add new build parameter to the pipeline
    Note:
    If you define custome build parameters directly, need to use these methods to notify library. Otherwise your definition will be overwritten by the pipeline definitions.
    Example:
    You manually defined a build parameter in your pipeline,
    def myBuildParamA = string( name: 'param_a', description: 'My custom build parameter A', defaultValue: 'default-value-of-a', trim: true, required: true ) // this line is not neccessary properties(parameters([myBuildParamA]))
    
    Then you may need to notify the pipeline with this code:
    
    // this line is required when you use Pipeline library pipeline.addBuildParameter(myBuildParamA)
    Parameters:
    param - build parameter
  - void addBuildParameters(java.util.List params)
    
    Add new build parameters to the pipeline
    This is a bulk way to add more than one build parameters.
    Example:
    pipeline.addBuildParameters([ string( name: 'param_a', description: 'My custom build parameter A', defaultValue: 'default-value-of-a', trim: true, required: true ), string( name: 'param_b', description: 'My custom build parameter B', defaultValue: 'default-value-of-b', trim: true, required: true ) ])
    See Also:
    addBuildParameter(def)
    Parameters:
    params - list of build parameters
  - void addBuildParameters(org.jenkinsci.plugins.structs.describable.UninstantiatedDescribable... params)
    
    Add new build parameters to the pipeline.
    This is a bulk way to add more than one build parameters.
    Example:
    pipeline.addBuildParameters(string( name: 'param_a', description: 'My custom build parameter A', defaultValue: 'default-value-of-a', trim: true, required: true ), string( name: 'param_b', description: 'My custom build parameter B', defaultValue: 'default-value-of-b', trim: true, required: true ))
    See Also:
    addBuildParameter(def)
    Parameters:
    params - list of build parameters
  - void addUpstreams(java.lang.String... upstreams)
    
    Define upstreams of the pipeline.
    Example:
    pipeline.addUpstreams('/Explorer-Data Sets/master', '/Explorer-Jobs/master')
    Parameters:
    upstreams - all upstreams
  - final Stage createStage(StageArguments args)
    
    Creates a new stage to be run in the Jenkins pipeline.
    Stages are executed in the order that they are created. For more details on what arguments can be sent into a stage, see the StageArguments class.
    
    Stages can also encounter various conditions that will cause them to skip. The following skip search order is used when determining if a stage should be skipped.
    1. If the StageArguments.resultThreshold value is greater than the current result, the stage will be skipped. There is no override for this operation.
    2. If the stage is skippable and the stage skip build option was passed, the stage will be skipped.
    3. If the remaining pipeline stages are to be skipped, then this stage will be skipped. This can be overridden if the stage has set StageArguments.doesIgnoreSkipAll to true.
    4. Finally, if the call to StageArguments.shouldExecute returns false, the stage will be skipped.
    If the stage is not skipped after executing the above checks, the stage will continue to its execute phase.
    
    Parameters:
    args - The arguments that define the stage.
    Returns:
    The created org.zowe.jenkins_shared_library.pipelines.base.models.Stage.
  - final Stage createStage(java.util.Map arguments)
    
    Creates a new stage to be run in the Jenkins pipeline.
    Parameters:
    arguments - A map of arguments that can be instantiated to a org.zowe.jenkins_shared_library.pipelines.base.arguments.StageArguments instance.
    Returns:
    The created org.zowe.jenkins_shared_library.pipelines.base.models.Stage.
    See Also:
    createStage(StageArguments)
  - protected void defineDefaultBranches()
    
    Setup default branch settings
    Note:
    To overwrite this default settings, you can re-define with same name:
    pipeline.branches.addMap([ [ name : 'master', isProtected : false, buildHistory : 10, ] ])
  - protected void end(EndArguments args)
    
    Pseudo end method, should be overridden by inherited classes
    Note:
    This method is added so we have consistency on creating pipeline with different level of Pipeline classes. No matter you use Base Pipeline, GenericPipeline, or GradlePipeline, etc, you have consistency on using setup(SetupStageArguments) and end(EndArguments) methods.
    
    Parameters:
    args - Arguments for the end method.
  - protected void end(java.util.Map args = [:])
    
    Pseudo end method, should be overridden by inherited classes
    Parameters:
    args - A map that can be instantiated as EndArguments.
  - final void endBase(EndArguments args)
    
    Signal that no more stages will be added and begin pipeline execution.
    The end method MUST be the last method called as part of your pipeline. The end method is responsible for executing all the stages previously created after setting the required build options and possible stage parameters. Failure to call this method will prevent your pipeline stages from executing.
    
    Prior to executing the stages, various build options are set. Some of these options include the build history and stage skip parameters. After this is done, the method will execute all of the created stages in the order they were defined.
    
    After stage execution, desired logs will be captured and an email will be sent out to those that made the commit. If the build failed or returned to normal, all committers since the last successful build will also receive the email. Finally if this build is on a protected branch, all emails listed in the admins list will also receive a status email.
    Note:
    This method was intended to be called end but had to be named endBase due to the issues described in Pipeline.
    
    Parameters:
    args - Arguments for the end method.
  - final void endBase(java.util.Map arguments = [:])
    
    Signal that no more stages will be added and begin pipeline execution.
    Parameters:
    arguments - A map that can be instantiated as EndArguments.
    See Also:
    endBase(EndArguments)
  - final Stage getFirstFailingStage()
    
    Gets the first failing stage within _stages
    Returns:
    The first failing stage if one exists, null otherwise
  - final Stage getStage(java.lang.String stageName)
    
    Get a stage from the available stages by name.
    Parameters:
    stageName - The name of the stage object to get.
    Returns:
    The stage object for the requested stage.
  - final void setResult(ResultEnum result)
    
    Set the build result
    Parameters:
    result - The new result for the build.
  - protected void setup(SetupStageArguments arguments)
    
    Pseudo setup method, should be overridden by inherited classes
    Parameters:
    arguments - The arguments for the added stages.
  - protected void setup(java.util.Map arguments = [:])
    
    Pseudo setup method, should be overridden by inherited classes
    Parameters:
    arguments - A map that can be instantiated as SetupStageArguments
  - void setupBase(SetupStageArguments arguments)
    
    Initialize the pipeline.
    This method MUST be called before any other stages are created. If not called, your Jenkins pipeline will fail. It is also recommended that any public properties of this class are set prior to calling setup.
    
    When extending the Pipeline class, this method must be called in any overridden setup methods. Failure to do so will result in the pipeline indicating that setup was never called.
    Stages:
    The setup method creates 2 stages in your Jenkins pipeline using the createStage(Map) function.
    
    Setup
    
    Used internally to indicate that the Pipeline has been properly setup.
    
    Checkout
    
    Checks the source out for the pipeline.
    
    Note:
    This method was intended to be called setup but had to be named setupBase due to the issues described in Pipeline.
    
    Parameters:
    arguments - The arguments for the added stages.
  - void setupBase(java.util.Map arguments = [:])
    
    Initialize the pipeline.
    Parameters:
    arguments - A map that can be instantiated as SetupStageArguments
    See Also:
    setupBase(SetupStageArguments)

Summary:
Field
Property
Constructor
Method

Groovy Documentation

[Groovy] Class Pipeline

Field Summary

Properties Summary

Constructor Summary

Methods Summary

Inherited Methods Summary

Field Detail

protected static final java.lang.String _SETUP_STAGE_NAME

protected PipelineControl _control

protected final org.zowe.jenkins_shared_library.email.Email _email

protected boolean _isProtectedBranch

protected boolean _shouldSkipRemainingStages

protected final Stages _stages

Property Detail

final PipelineAdmins admins

java.lang.String baseDirectory

Branches<org.zowe.jenkins_shared_library.pipelines.base.models.Branch> branches

java.util.List buildOptions

java.util.List buildParameters

java.util.List<java.lang.String> buildUpstreams

java.lang.String packageName

java.lang.Object steps

java.lang.String version

Constructor Detail

Pipeline(java.lang.Object steps)

Method Detail

protected final void _closureWrapper(Stage stage, groovy.lang.Closure closure)

protected static java.lang.String _getStageSkipOption(Stage stage)

protected void _sendEmailNotification()

void addBuildOption(java.lang.Object option)

void addBuildParameter(java.lang.Object param)

void addBuildParameters(java.util.List params)

void addBuildParameters(org.jenkinsci.plugins.structs.describable.UninstantiatedDescribable... params)

void addUpstreams(java.lang.String... upstreams)

final Stage createStage(StageArguments args)

final Stage createStage(java.util.Map arguments)

protected void defineDefaultBranches()

protected void end(EndArguments args)

protected void end(java.util.Map args = [:])

final void endBase(EndArguments args)

final void endBase(java.util.Map arguments = [:])

final Stage getFirstFailingStage()

final Stage getStage(java.lang.String stageName)

final void setResult(ResultEnum result)

protected void setup(SetupStageArguments arguments)

protected void setup(java.util.Map arguments = [:])

void setupBase(SetupStageArguments arguments)

void setupBase(java.util.Map arguments = [:])