How to Integrate Custom Pipeline Steps in Jenkins?

jenkins-plugin-cli --plugins workflow-step-api:657.v03b_e8115821b_

Workflow Step API

Seamlessly integrate custom Pipeline steps in Jenkins.

What is Pipeline: Step API Plugin?​

Plugins aiming to introduce custom Pipeline steps should add a dependency on the workflow-step-api. It's crucial to ensure that the baseline Jenkins version you are working with matches or exceeds the requirements of the Pipeline component plugins you're using. These requirements are typically listed on the plugin wikis.

This careful alignment helps avoid compatibility issues, ensuring that our custom steps integrate smoothly with the broader Jenkins Pipeline infrastructure.

How to Create Synchronous Pipeline Steps in Jenkins?​

Creating a synchronous pipeline step that executes quick, non-blocking operations involves several key steps:

1. Extend Step:

   • Define mandatory parameters in a @DataBoundConstructor.
   • Define optional parameters using @DataBoundSetter.
   • Ensure both have matching getters.

2. Create an Execution Class:

   • Typically, create a nested private static class named Execution.
   • Extend SynchronousNonBlockingStepExecution (or SynchronousStepExecution for trivial steps).
   • Parameterize it with the desired return value of the step (use Void if no return value is needed).
   • Implement the run method to perform the step's tasks.
   • Pass the Step object to the StepExecution constructor to access its configuration.
   • Use StepContext.get to obtain contextual objects needed for the step (commonly Run, TaskListener, FilePath, EnvVars, Launcher).

3. Extend StepDescriptor:

   • Provide a display name and a function name for use in Groovy scripts.

4. Create a config.jelly Form:

   • Design a form with databinding for all parameters for use from the Snippet Generator.
   • Use StepConfigTester from the workflow-step-api tests classifier to verify correct data binding.
   • Optionally, add methods for field validation and other configurations complementing config.jelly.

Note:​

Older Pipeline versions used Guice for injecting configuration and contextual objects into executions. This method is still possible but not recommended. If you must use an older version of workflow-step-api for creating a non-blocking synchronous step, you might need to use AbstractStepImpl, AbstractStepDescriptorImpl, AbstractSynchronousNonBlockingStepExecution, @Inject, and @StepContextParameter.