Pipeline: Step API Plugin

Developer Guide: Writing Pipeline steps

Plugins can implement custom Pipeline steps with specialized behavior by adding a dependency on workflow-step-api. Remember to ensure that your baseline Jenkins version is at least as new as that required by the versions of various Pipeline component plugins you are depending on. (The plugin wikis will note these baselines.)

Creating a basic synchronous step

When a Pipeline step does something quick and nonblocking, you can make a “synchronous” step. The Groovy execution waits for it to finish.

Extend Step. Define mandatory parameters in a @DataBoundConstructor. Define optional parameters using @DataBoundSetter. (Both need matching getters.)

Create a class, conventionally a nested private static class Execution, and extend SynchronousNonBlockingStepExecution (or SynchronousStepExecution for certain trivial steps). Parameterize it with the desired return value of the step (or Void if it need not return a value). The run method should do the work of the step. You can pass the Step object to the StepExecution constructor to access its configuration. Use StepContext.get to obtain contextual objects you require; commonly required types include Run, TaskListener, FilePath, EnvVars, and Launcher (these will be enumerated in StepDescriptor.getRequiredContext).

Extend StepDescriptor. Besides a display name, pick a function name which will be used from Groovy scripts.

Create a config.jelly form with databinding for all the parameters, for use from Snippet Generator. You can use the StepConfigTester test utility in workflow-step-api (tests classifier) to verify that all fields are correctly bound. The descriptor can also have the usual methods complementing config.jelly for field validation, etc.

Note: older versions of Pipeline used Guice for injecting step configuration and contextual objects into the execution. This is still possible, but not recommended. If you must depend on an old version of workflow-step-api, and you are creating a non-blocking synchronous step, you will be obliged to use AbstractStepImpl, AbstractStepDescriptorImpl, AbstractSynchronousNonBlockingStepExecution, @Inject, and @StepContextParameter.

Creating an asynchronous step

For the more general case that a Pipeline step might block in network or disk I/O, and might need to survive Jenkins restarts, you can use a more powerful API. This relies on a callback system: the Pipeline engine tells your step when to start, and your step tells Pipeline when it is done.

Extend StepExecution rather than SynchronousStepExecution or SynchronousNonBlockingStepExecution. You will be implementing a start method. Normally it should do any quick setup work and then return false, meaning the step is still running. Later you can call getContext().onSuccess(returnValue) (once) to make the step complete normally. Or, getContext().onFailure(error) to make the step throw an exception.

You can keep transient fields for caching purposes; override onResume to recreate transient state after a Jenkins restart if you need to. You can also keep non-transient fields, assuming they are Serializable. Do not forget to declare

private static final long serialVersionUID = 1L;

You should also implement stop to terminate the step. It could simply read

getContext().onFailure(cause);

but generally it will need to interrupt whatever process you started.

Creating a block-scoped step

Pipeline steps can also take “closures”: a code block which they may run zero or more times, optionally with some added context.

Override takesImplicitBlockArgument in your descriptor. In start, or thereafter, call

getContext().newBodyInvoker().
        withContext(…something…).
        withCallback(BodyExecutionCallback.wrap(getContext())).
        start();

The above returns the same value as the block. The callback may also be a TailCall to do some cleanup, or any other BodyExecutionCallback to customize handling of the end of the block.

You can pass various contextual objects, as per StepContext.get above.

stop is optional.

Using more APIs

You can also add a dependency on workflow-api which brings in more Pipeline-specific features. For example you can then receive a FlowNode from StepContext.get and call addAction to customize the Pipeline Steps view.

Version history

See the changelog