Library Steps¶
Library Steps are a mechanism for modularizing pipeline functionality.
Naming A Step¶
By default, the name of the step that's loaded is based on the filename without the .groovy
extension.
This can be modified using Step Aliasing.
Best Practice
It's recommended that Step Aliasing only be used when actually necessary.
The call
Method¶
Most steps should implement the call
method.
void call(){}
This makes it such that the step can be invoked via its name.
For example, a step named build.groovy
that has implemented a call
method can be invoked via build()
.
Why the Call Method?
Curious readers commonly ask, "Why the call method?"
The answer comes from the Groovy Call Operator.
Essentially, build()
is equivalent to build.call()
in groovy.
Autowired Variables¶
All Library Steps are autowired with several variables:
Variable | Description |
---|---|
config |
The library's block of configuration for the library that contributed the step. |
stepContext |
Information about the step that's currently running. |
stageContext |
Information about the current Stage, if applicable |
hookContext |
If this step was triggered by a Lifecycle Hook, information about the trigger |
Reference
For more information, check out the Autowired Variables page
Method Parameters¶
Library Steps can accept method parameters just like any other method.
Library Step Method Parameters
void call(String message){
println "here's your message: ${message}"
}
printMessage("hello, world!")
Be Careful!
Library Steps that accept method parameters run a high risk of breaking the interoperability of the Pipeline Template.
Imagine the scenario where the Pipeline Template invokes a build()
step and the same template is intended to be used across teams that may be using different tools, such as gradle
and npm
.
If the gradle
library's build()
step accepts a set of parameters and the npm
library's build()
step doesn't then you won't be able to swap out the libraries interchangeably.
Instead of method parameters, consider passing steps information via the Pipeline Configuration using the config
variable.
Check out the Parameterizing Libraries page to learn more.
The exception to the rule of thumb regarding method parameters is when the method parameters are Pipeline Primitives. This works because the parameters can then be interchanged safely along with the implementation of the step that's accepting them as an argument.
The most common example is creating a deployment step.
Frequently, teams will create a deploy_to
step that accepts an Application Environment as an argument.
Deployment Steps
The following Pipeline Template, Pipeline Configuration, and Deployment step demonstrate a safe use of a library step accepting a method parameter.
unit_test()
build()
deploy_to dev
smoke_test()
deploy_to prod
libraries{
npm // contributes unit_test, build
cypress // contributes integration_test
ansible // contributes deploy_to
}
application_environments{
dev{
ip = "1.1.1.1"
}
prod{
ip = "2.2.2.2"
}
}
void call(app_env){
println "deploying to the ip: ${app_env.ip}"
}
Advanced Topics¶
This page has covered the basics, if you're ready for more check out the following pages:
Topic | Description |
---|---|
Lifecycle Hooks | Learn how to trigger Library Steps implicitly. |
Multi-Method Library Steps | Learn how to define more than one method in a step. |
Step Aliasing | Learn how to call the same step by multiple names. |