The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.
For a list of other such plugins, see the Pipeline Steps Reference page.
catchError
: Catch error and set build result to failuredeleteDir
: Recursively delete the current directory from the workspacedir
: Change current directoryecho
: Print Messageerror
: Error signalfileExists
: Verify if file exists in workspaceisUnix
: Checks if running on a Unix-like nodemail
: Mailpwd
: Determine current directoryreadFile
: Read file from workspaceretry
: Retry the body up to N timessleep
: Sleepstash
: Stash some files to be used later in the buildstep
: General Build Steptimeout
: Enforce time limittool
: Use a tool from a predefined Tool Installationunstable
: Set stage result to unstableunstash
: Restore files previously stashedwaitUntil
: Wait for conditionwarnError
: Catch error and set build and stage result to unstablewithEnv
: Set environment variableswrap
: General Build WrapperwriteFile
: Write file to workspacearchive
: Archive artifactsgetContext
: Get contextual object from internal APIsunarchive
: Copy archived artifacts into the workspacewithContext
: Use contextual object from internal APIs within a blockcatchError
: Catch error and set build result to failurecatchError
step. The behavior of the step when an exception is thrown can be configured to print a message, set a build result other than failure, change the stage result, or ignore certain kinds of exceptions that are used to interrupt the build.
This step is most useful when used in Declarative Pipeline or with the options to set the stage result or ignore build interruptions. Otherwise, consider using plain try
-catch
(-finally
) blocks. It is also useful when using certain post-build actions (notifiers) originally defined for freestyle projects which pay attention to the result of the ongoing build.
node { catchError { sh 'might fail' } step([$class: 'Mailer', recipients: 'admin@somewhere']) }
If the shell step fails, the Pipeline build’s status will be set to failed, so that the subsequent mail step will see that this build is failed. In the case of the mail sender, this means that it will send mail. (It may also send mail if this build succeeded but previous ones failed, and so on.) Even in that case, this step can be replaced by the following idiom:
node { try { sh 'might fail' } catch (err) { echo "Caught: ${err}" currentBuild.result = 'FAILURE' } step([$class: 'Mailer', recipients: 'admin@somewhere']) }
For other cases, plain try
-catch
(-finally
) blocks may be used:
node { sh './set-up.sh' try { sh 'might fail' echo 'Succeeded!' } catch (err) { echo "Failed: ${err}" } finally { sh './tear-down.sh' } echo 'Printed whether above succeeded or failed.' } // …and the pipeline as a whole succeeds
See this document for background.
buildResult : String
(optional)
SUCCESS
if the current result is UNSTABLE
or worse. Use SUCCESS
or null
to keep the build result from being set when an error is caught.
catchInterruptions : boolean
(optional)
timeout
step. Defaults to true.
message : String
(optional)
stageResult : String
(optional)
SUCCESS
or null
to keep the stage result from being set when an error is caught.
deleteDir
: Recursively delete the current directory from the workspacedeleteDir
step in a dir
step.
dir
: Change current directorydir
block will use this directory as current and any relative path will use it as base path.
path : String
error
: Error signalthrow new Exception()
, but this step will avoid printing a stack trace.
message : String
fileExists
: Verify if file exists in workspacetrue | false
. This step must be run inside a node
context:
# Declarative Syntax stage ('Check for existence of index.html') { agent any # Could be a top-level directive or a stage level directive steps { script { if (fileExists('src/main/rersources/index.html') { echo "File src/main/rersources/index.html found!" } } } }With the Declarative Syntax, it must be run in a stage with a defined agent (e.g. different than `agent none`):
# Scripted Syntax node { if (fileExists('src/main/rersources/index.html') { echo "File src/main/rersources/index.html found!" } }
file : String
/separator:
node('Linux') { if (fileExists('/usr/local/bin/jenkins.sh') { sh '/usr/local/bin/jenkins.sh' } } node('Windows') { if (fileExists('C:/jenkins.exe') { bat 'C:/jenkins.exe' } }When using a Windows path with the backslash (
\) separator, do not forget to escape it:
node('Windows') { if (fileExists('src\\main\\resources') { echo 'Found a directory resources.' } }
isUnix
: Checks if running on a Unix-like nodenode
is running on a Unix-like system (such as Linux or Mac OS X), false if Windows.
mail
: Mailsubject : String
body : String
bcc : String
(optional)
cc : String
(optional)
charset : String
(optional)
UTF-8
from : String
(optional)
mimeType : String
(optional)
text/plain
.
replyTo : String
(optional)
to : String
(optional)
pwd
: Determine current directorytmp : boolean
(optional)
readFile
: Read file from workspacefile : String
/
-separated) path to file within a workspace to read.
encoding : String
(optional)
retry
: Retry the body up to N timescount : int
conditions
(optional)
agent
node
block, or certain steps inside it such as sh
, failed for reasons which are likely due to infrastructure rather than the behavior of the build. If the connection to an agent is broken or the agent is removed from the list of executors while in use (typically in response to the disappearance of underlying cloud resources), this condition will allow retry
to allocate a fresh agent and try the whole block again.
kubernetesAgent
agent()
(Agent errors) but tailored to agents provisioned from a Kubernetes cloud. Unlike the generic agent error condition, this will ignore certain pod termination reasons which are likely to be under the control of the Pipeline author (e.g., OOMKilled
) while still allowing retry
to recover after common cases of pod deletion.
handleNonKubernetes : boolean
(optional)
agent()
(Agent errors) when applied to a non-Kubernetes agent. Useful in cases where it is hard to predict in a job definition whether a Kubernetes or other sort of agent will be used.
nonresumable
sh
or input
are written to survive a Jenkins restart and simply pick up where they left off when the build resumes. Others like checkout
or junit
normally complete promptly but cannot tolerate a restart. In case one of these steps happened to be in progress when Jenkins shut down, the resumed build will throw an error; using this condition with retry
allows the step (or the whole enclosing node
block) to be rerun.
sleep
: Sleepsh 'sleep …'
. May be used to pause one branch of parallel
while another proceeds.
time : int
unit
(optional)
NANOSECONDS
, MICROSECONDS
, MILLISECONDS
, SECONDS
, MINUTES
, HOURS
, DAYS
stash
: Stash some files to be used later in the buildpreserveStashes()
option to allow stashes from a run to be retained and used if that run is restarted. archiveArtifacts
instead. Note that the stash
and unstash
steps are designed for use with small files. For large data transfers, use the External Workspace Manager plugin, or use an external repository manager such as Nexus or Artifactory. This is because stashed files are archived in a compressed TAR, and with large files this demands considerable on-master resources, particularly CPU time. There's not a hard stash size limit, but between 5-100 MB you should probably consider alternatives.
name : String
allowEmpty : boolean
(optional)
false
(default), an error is raised when the stash does not contain files.
excludes : String
(optional)
includes : String
(optional)
**
: all files.dir
.
useDefaultExcludes : boolean
(optional)
step
: General Build StepThis is a special step that allows to call builders or post-build actions (as in freestyle or similar projects), in general "build steps". Just select the build step to call from the dropdown list and configure it as needed.
Note that only Pipeline-compatible steps will be shown in the list.
step([$class: 'A3Builder'])
.
timeout
: Enforce time limittime : int
activity : boolean
(optional)
unit
(optional)
NANOSECONDS
, MICROSECONDS
, MILLISECONDS
, SECONDS
, MINUTES
, HOURS
, DAYS
tool
: Use a tool from a predefined Tool InstallationConfigure System
are available here. If the original tool installer has the auto-provision feature, then the tool will be installed as required.
name : String
type : String
(optional)
unstable
: Set stage result to unstableUNSTABLE
. The message will also be associated with the stage result and may be shown in visualizations.
message : String
unstash
: Restore files previously stashedstash
ed into the current workspace.
name : String
waitUntil
: Wait for conditiontrue
. If it returns false
, waits a while and tries again. (Subsequent failures will slow down the delay between attempts up to a maximum of 15 seconds.) There is no limit to the number of retries, but if the body throws an error that is thrown up immediately.
initialRecurrencePeriod : long
(optional)
quiet : boolean
(optional)
warnError
: Catch error and set build and stage result to unstableUNSTABLE
, prints a specified message and the thrown exception to the build log, and associates the stage result with the message so that it can be displayed by visualizations.
Equivalent to catchError(message: message, buildResult: 'UNSTABLE', stageResult: 'UNSTABLE')
.
message : String
catchInterruptions : boolean
(optional)
timeout
step. Defaults to true.
withEnv
: Set environment variablesnode { withEnv(['MYTOOL_HOME=/usr/local/mytool']) { sh '$MYTOOL_HOME/bin/start' } }
(Note that here we are using single quotes in Groovy, so the variable expansion is being done by the Bourne shell, not Jenkins.)
See the documentation for the env
singleton for more information on environment variables.
overrides : Array / List of String
VARIABLE=value
or VARIABLE=
to unset variables otherwise defined. You may also use the syntax PATH+WHATEVER=/something
to prepend /something
to $PATH
.
wrap
: General Build WrapperThis is a special step that allows to call build wrappers (also called "Environment Configuration" in freestyle or similar projects). Just select the wrapper to use from the dropdown list and configure it as needed. Everything inside the wrapper block is under its effect.
Note that only Pipeline-compatible wrappers will be shown in the list.
wrap([$class: 'AnsiColorBuildWrapper'])
.
writeFile
: Write file to workspacefile : String
text : String
encoding : String
(optional)
archive
: Archive artifactsarchiveArtifacts
.
includes : String
excludes : String
(optional)
getContext
: Get contextual object from internal APIsObtains a contextual object as in StepContext.get
; cf. withContext
. Takes a single type
argument. Example:
getContext hudson.FilePath
For use from trusted code, such as global libraries, which can manipulate internal Jenkins APIs.
type
java.lang.Class<?>
unarchive
: Copy archived artifacts into the workspacemapping
(optional)
java.util.Map<java.lang.String, java.lang.String>
withContext
: Use contextual object from internal APIs within a blockWraps a block in a contextual object as in BodyInvoker.withContext
; cf. getContext
. Takes a single context
argument plus a block. Example:
withContext(new MyConsoleLogFilter()) {
sh 'process'
}
Automatically merges its argument with contextual objects in the case of ConsoleLogFilter
, LauncherDecorator
, and EnvironmentExpander
.
For use from trusted code, such as global libraries, which can manipulate internal Jenkins APIs.
Do not attempt to pass objects defined in Groovy; only Java-defined objects are supported. Really you should avoid using this and getContext
and just define a Step
in a plugin instead.
context : Object
Please submit your feedback about this page through this quick form.
Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?
See existing feedback here.