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
(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.
String
catchInterruptions
(optional)
timeout
step.
boolean
message
(optional)
String
stageResult
(optional)
SUCCESS
or null
to keep the stage result from being set when an error is caught.
String
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
.
file
/
-separated) path to file within a workspace to verify its existence.
String
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
(optional)
String
cc
(optional)
String
charset
(optional)
UTF-8
String
from
(optional)
String
mimeType
(optional)
text/plain
.
String
replyTo
(optional)
String
to
(optional)
String
pwd
: Determine current directorytmp
(optional)
boolean
readFile
: Read file from workspacefile
/
-separated) path to file within a workspace to read.
String
encoding
(optional)
String
retry
: Retry the body up to N timescount
int
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
(optional)
boolean
excludes
(optional)
String
includes
(optional)
**
: all files.
dir
.
String
useDefaultExcludes
(optional)
boolean
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
(optional)
boolean
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
(optional)
String
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
(optional)
long
quiet
(optional)
boolean
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
(optional)
timeout
step.
boolean
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
VARIABLE=value
or VARIABLE=
to unset variables otherwise defined. You may also use the syntax PATH+WHATEVER=/something
to prepend /something
to $PATH
.
String
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
(optional)
String
archive
: Archive artifactsarchiveArtifacts
.
includes
String
excludes
(optional)
String
getContext
: Get contextual object from internal APIs Obtains 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 block Wraps 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.