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.
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
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
Launcher (these will be enumerated in
StepDescriptor. Besides a display name, pick a function name which will be used from Groovy scripts.
config.jelly form with databinding for all the parameters, for use from Snippet Generator. You can use the
StepConfigTester test utility in
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
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.
StepExecution rather than
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
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.
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
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
StepContext.get and call
addAction to customize the Pipeline Steps view.
See the changelog