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.

Pipeline: Basic Steps

archive: Archive artifacts

Archives build output artifacts for later use. As of Jenkins 2.x, you may use the more configurable archiveArtifacts.
includes
Include artifacts matching this Ant style pattern. Use a comma separated list to add more than one expression.

Type: String

excludes (optional)
Exclude artifacts matching this Ant-style pattern. Use a comma-separated list to add more than one expression.

Type: String

deleteDir: Recursively delete the current directory from the workspace

Recursively deletes the current directory and its contents. Symbolic links and junctions will not be followed but will be removed. To delete a specific directory of a workspace wrap the deleteDir step in a dir step.

dir: Change current directory

Change current directory. Any step inside the dir block will use this directory as current and any relative path will use it as base path.
path

Type: String

echo: Print Message

message

Type: String

error: Error signal

Signals an error. Useful if you want to conditionally abort some part of your program. You can also just throw new Exception(), but this step will avoid printing a stack trace.
message

Type: String

fileExists: Verify if file exists in workspace

Checks if the given file (as relative path to current directory) exists. Returns true | false.
file
Relative ( /-separated) path to file within a workspace to verify its existence.

Type: String

isUnix: Checks if running on a Unix-like node

Returns true if enclosing node is running on a Unix-like system (such as Linux or Mac OS X), false if Windows.

mail: Mail

Simple step for sending email.
subject
Email subject line.

Type: String

body
Email body.

Type: String

bcc (optional)
BCC email address list. Comma separated list of email addresses.

Type: String

cc (optional)
CC email address list. Comma separated list of email addresses.

Type: String

charset (optional)
Email body character encoding. Defaults to UTF-8

Type: String

from (optional)
From email address. Defaults to the admin address globally configured for the Jenkins instance.

Type: String

mimeType (optional)
Email body MIME type. Defaults to text/plain.

Type: String

replyTo (optional)
Reploy-To email address. Defaults to the admin address globally configured for the Jenkins instance.

Type: String

to (optional)
To email address list. Comma separated list of email addresses.

Type: String

pwd: Determine current directory

Returns the current directory path as a string.
tmp (optional)
If selected, return a temporary directory associated with the workspace rather than the workspace itself. This is an appropriate place to put temporary files which should not clutter a source checkout; local repositories or caches; etc.

Type: boolean

readFile: Read file from workspace

Reads a file from a relative path (with root in current directory, usually workspace) and returns its content as a plain string.
file
Relative ( /-separated) path to file within a workspace to read.

Type: String

encoding (optional)

Type: String

retry: Retry the body up to N times

Retry the block (up to N times) if any exception happens during its body execution. If an exception happens on the final attempt then it will lead to aborting the build (unless it is caught and processed somehow). User aborts of the build are not caught.
count

Type: int

sleep: Sleep

Simply pauses the Pipeline build until the given amount of time has expired. Equivalent to (on Unix) sh 'sleep …'. May be used to pause one branch of parallel while another proceeds.
time

Type: int

unit (optional)

Values:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

stash: Stash some files to be used later in the build

Saves a set of files for use later in the same build, generally on another node/workspace. Stashed files are not otherwise available and are generally discarded at the end of the build. 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
Name of a stash. Should be a simple identifier akin to a job name.

Type: String

allowEmpty (optional)

Type: boolean

excludes (optional)
Optional set of "Ant-style exclude patterns.
Use a comma separated list to add more than one expression.
If blank, no file will be excluded.

Type: String

includes (optional)
Optional set of "Ant-style include patterns.
Use a comma separated list to add more than one expression.
If blank, treated like **: all files.
The current working directory is the base directory for the saved files, which will later be restored in the same relative locations, so if you want to use a subdirectory wrap this in dir.

Type: String

useDefaultExcludes (optional)
If selected, use the default excludes from Ant - see here for the list.

Type: boolean

timeout: Enforce time limit

Executes the code inside the block with a determined time out limit. If the time limit is reached, an exception is thrown, which leads in aborting the build (unless it is caught and processed somehow).
time

Type: int

unit (optional)

Values:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

tool: Use a tool from a predefined Tool Installation

Binds a tool installation to a variable (the tool home directory is returned). Only tools already configured in Configure System are available here. If the original tool installer has the auto-provision feature, then the tool will be installed as required.
name

Type: String

type (optional)

Type: String

unstash: Restore files previously stashed

Restores a set of files previously stashed into the current workspace.
name
Name of a previously saved stash.

Type: String

waitUntil: Wait for condition

Runs its body repeatedly until it returns true. If it returns false, waits a while and tries again. (Subsequent failures will slow down the delay between attempts.) There is no limit to the number of retries, but if the body throws an error that is thrown up immediately.

withEnv: Set environment variables

Sets one or more environment variables within a block. These are available to any external processes spawned within that scope. For example:

node {
  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
A list of environment variables to set, each in the form VARIABLE=value or VARIABLE= to unset variables otherwise defined. You may also use the syntax PATH+WHATEVER=/something to prepend /something to $PATH.

Array/List

Type: String

wrap: General Build Wrapper

This 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.

delegate

Nested Choice of Objects $class: AnsiColorBuildWrapper colorMapName:::

+ Type: String

$class: AntWrapper

Prepares an environment for Jenkins to run builds using Apache Ant. Annotates Ant-specific output to display executed targets. Optionally sets up an Ant and/or JDK installation.
installation (optional)

Name of an Ant installation to use so that ant will be in the path.

Type: String

jdk (optional)

Name of an Java installation to use when running Ant.

Type: String

$class: BuildUser

This plugin is used to set user build variables:
  • BUILD_USER -- full name of user started build,
  • BUILD_USER_FIRST_NAME -- first name of user started build,
  • BUILD_USER_LAST_NAME -- last name of user started build,
  • BUILD_USER_ID -- id of user started build.
  • BUILD_USER_EMAIL -- email of user started build.

$class: CacheWrapper

Enable caching of files on the executor so that subsequent builds do not need to recreate the files. This is helpful for executors that start clean each time such as docker containers.
maxCacheSize

Type: long

caches

Array/List

Nested Choice of Objects $class: ArbitraryFileCache

Caches arbitrary paths on the executor back to the item storage cache.
path
The path that should be cached from build to build.

Type: String

includes
Pattern to match files that should be included during caching

Type: String

excludes
Pattern of excludes that should be avoided during caching

Type: String

$class: ConfigFileBuildWrapper

Make globally configured files available in you local workspace. All files configured via the config-file-provider plugin are available an can be referenced.
managedFiles

Array/List

Nested Object

fileId

Type: String

replaceTokens (optional)

Type: boolean

targetLocation (optional)

Type: String

variable (optional)

Type: String

$class: ConsulKVReadWrapper reads:::

+ Array/List

Nested Object

aclToken
Token is used to supply UUID token for Consul ACL token calls. Token can be supplied by build parameters.

Type: String

hostUrl
Host URL should contain protocol (HTTP/HTTPS)://<HOST_NAME>.

Type: String

key
Key is used in GET/PUT requests to lookup the value from, or right the key/value pair to the Consul key/value store.

Type: String

envKey
ENV Varaible Key is used to store the retrieved value in the build ENV variables to be used downstream.

Type: String

apiUri (optional)
URL Override is used to override the K,V API URL.

Type: String

debugMode (optional)
Enable Debug messages for more verbose logging.

Values:

  • ENABLED

  • DISABLED

    ignoreGlobalSettings (optional)

    Type: boolean

    timeoutConnect (optional)
    Connection timeout in milliseconds, default is 10000.

Type: int

timeoutResponse (optional)
Response timeout in milliseconds, default is 30000.

Type: int

$class: CoverityEnvBuildWrapper

This step will use the specified Coverity Tool Installation and add the bin/ directory to PATH for any steps that are wrapped. This will allow the pipeline script to access Coverity tools (like cov-build, cov-analyze, and cov-commit-defects) directly from a script step (such as a Shell Script or Windows Batch Script).
coverityToolName

Type: String

$class: DockerMachineWrapper name:::

+

Override the default docker-machine name for this project.
You can use environment variables.
The default value is jenkins-$JOB_NAME, which means a CloudShare environment by the name of docker-machine-jenkins-[job name] would be used (docker-machine- is always prefixed by the docker-machine driver).
Remember to also in configure the CloudShare API keys.

Type: String

expiryDays

Type: String

$class: JiraCreateReleaseNotes jiraProjectKey:::

+

Specify JIRA project key. A project key is the all capitals part before the issue number in JIRA.

(EXAMPLE-100)

Type: String

jiraRelease

Specify the name of the parameter which will contain the release version. This can reference a build parameter.

Type: String

jiraEnvironmentVariable

Specify the environment variable to which the release notes will be stored, defaults to RELEASE_NOTES.

This can be used in another build step which supports environments.

Type: String

jiraFilter

Apply additional filtering criteria to the issue filter. This will be concatenated with an AND operator.

Defaults To:

status in (Released, Closed)

Type: String

$class: KlocworkBuildWrapper serverConfig:::

+

Server configurations are created on the Configure System page

Type: String

installConfig
Install configurations are created on the Configure System page. When used, the specified PATHs are added to the launcher to be used by any build step

Type: String

serverProject
The Klocwork server project to run a server build against or to connect a Klocwork desktop analysis to

Type: String

ltoken
(Optional) Specify a custom ltoken location. The Klocwork ltoken is used to authenticate with the Klocwork server. The default ltoken location is in the user's home directory, that is the user running the process. More information

Type: String

$class: KubectlBuildWrapper

Configure Kubernetes client (kubectl) so it can be used in the build to run Kubernetes commands
serverUrl
URL of the Kubernetes API endpoint. If not set the connection options will be autoconfigured from service account or kube config file.

Type: String

credentialsId

Type: String

caCertificate
The base64 encoded certificate of the certificate authority (CA). It is used to verify the server certificate.

Leaving this field empty will skip the certificate verification.

Type: String

$class: MaskPasswordsBuildWrapper

When enabled, allows masking passwords that may appear in the console.

Passwords or regexes to be masked can be defined at three levels.

First, it is possible to select in Hudson's/Jenkins' configuration screen the build parameters whose value must be masked. For example, selecting the Password Parameter type is a good idea.

Second, still in Hudson's/Jenkins' configuration screen, it is possible to define passwords to be masked as global Name/Password pairs, or regexes to be masked.

Third, on a per job basis (that is, in the current configuration screen), passwords to be masked can be defined as local Name/Password pairs, or regexes can be masked:

  • Password is aimed at containing a password to be masked from the console. Empty and blank values are not allowed (e.g. " ", etc.). This field is ciphered. This field can not contain variables, they won't be expanded.
  • If Name is set, then a build variable will be defined accordingly. This allows accessing the password by using the variable rather than hard-coding it in a field which is not ciphered (e.g. the ones of the Invoke Ant or Execute shell build steps).
  • If Regex is set, then any text matching that regex will be masked in the console output. The regex should not contain start- or end-of-string markers and will be internally and-ed (piped) together with all other regexes and regexes matching the specified names and passwords.
varPasswordPairs

Array/List

Nested Object

var

Type: String

password

Type: String

varMaskRegexes

Array/List

Nested Object

regex

Type: String

$class: MesosSingleUseSlave

If checked, the Mesos slaves allocated for a build of this job will be used exclusively by the build. Once the build is completed, it will be flagged as offline then disconnected.

$class: NodeJSBuildWrapper nodeJSInstallationName:::

+ Type: String

configId (optional)

Type: String

$class: RepositoryDefinitionProperty

If selected, this allows you to define a variable - Jenkins.Repository - that will be present in the Maven environment that points to the specified repository.
The best way of using this is to create a profile in the Jenkins settings.xml:


        <profile>
            <id>jenkins</id>
            <repositories>
                <repository>
                    <id>jenkins</id>
                    <url>${env.Jenkins.Repository}</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>jenkins</id>
                    <url>${env.Jenkins.Repository}</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </pluginRepository>
            </pluginRepositories>
        </profile>

    

This profile is then enabled by adding "-Pjenkins" to your maven build options.
upstream

Nested Choice of Objects $class: SelectionTypeProject project::::

+ Type: String

build

Type: String

promoted

Type: String

$class: SelectionTypeSpecified path::::

+ Type: String

$class: SelectionTypeUpstream build::::

+ Type: String

$class: SonarBuildWrapper installationName:::

+ Type: String

$class: TABuildWrapper

The below properties will be available as build variables in all the build steps during build. You can use them to register test run on your own (in your scripts).

Also the properties set in global plugin configuration ("Dynatrace Application Monitoring" config section) will be available as build variables: 'dtServerUrl', 'dtUsername' and 'dtPassword'.

NOTE:
If you decide not to use the below properties in your scripts and to register test runs on your own, please fill at least the "System profile" field to have the post-build action working properly.

systemProfile

Type: String

marker (optional)

Type: String

recordSession (optional)

Type: boolean

versionMajor (optional)

Type: String

versionMilestone (optional)

Type: String

versionMinor (optional)

Type: String

versionRevision (optional)

Type: String

$class: TimestamperBuildWrapper $class: VaultBuildWrapper vaultSecrets:::

+ Array/List

Nested Object

path
The path of the secret in the vault server as described here.

Type: String

secretValues

Array/List

Nested Object

envVar:
The environment variable to set with the value of the vault key.

Type: String

vaultKey:
The vault key whose value with populate the environment variable.

Type: String

configuration (optional)

Nested Object

vaultUrl (optional)

Type: String

vaultCredentialId (optional)

Type: String

$class: Xvfb additionalOptions (optional):::

+

Additional options to be added with the options above to the Xvfb command line.

Type: String

assignedLabels (optional)
If you want to start Xvfb only on specific nodes specify its name or label. See the Restrict where this project can be run option for label expressions that you can use.

Type: String

autoDisplayName (optional)
Uses the -displayfd option of Xvfb by which it chooses it’s own display name by scanning for an available one. This option requires a recent version of xserver, check your installation for support.

Type: boolean

debug (optional)
If Xvfb output should appear in console log of this job, useful only if debugging Xvfb interaction.

Type: boolean

displayName (optional)
Ordinal of the display Xvfb will be running on, if left empty (default) choosen based on current build executor number. Use only if you know what you’re doing, could leed to clashes with other builds.

Type: int

displayNameOffset (optional)
Offset for display names, default is 1. Display names are taken from build executor’s number, i.e. if the build is performed by executor 4, and offset is 100, display name will be 104.

Type: int

installationName (optional)
The name of the Xvfb tool installation that Jenkins administrator set up.

Type: String

parallelBuild (optional)
When running multiple Jenkins nodes on the same machine this setting influences the display number generation. The display number will be based upon node position in the list of nodes multiplied by 100 to which current executor number and any given offset will be added. Using this with offset set to 0 there is a limit of 595 nodes and 35 executors on a node, having more nodes or executors is not compatible with this option.

Type: boolean

screen (optional)
Resolution and color depth of the created virtual frame buffer in the format WxHxD. For example: 1024x758x16

Type: String

shutdownWithBuild (optional)
Should the display be kept until the whole job ends (including the post build steps).

Type: boolean

timeout (optional)
A timeout of given seconds to wait before returning control to the job, this allows Xvfb to start before there is a need for it. By default set to 0, not to delay the build, since it usualy takes just a few seconds for Xvfb to start, and outputting to display is not the first thing a job does.

Type: long

$class: Xvnc

If checked, Xvnc will be run during this build to provide X display. The X display number will be set to DISPLAY environment variable.
takeScreenshot
Optionally, upon completion of the build, a screenshot can be taken. This requires ImageMagick be installed.

Type: boolean

useXauthority

Type: boolean

writeFile: Write file to workspace

Write the given content to a named file in the current directory.
file

Type: String

text

Type: String

encoding (optional)

Type: String

catchError: Catch error and set build result

If the body throws an exception, mark the build as a failure, but nonetheless continue to execute the Pipeline from the statement following the catchError step. This is only necessary 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 all other cases, use plain try-catch(-finally) blocks:

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.

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 workspace

mapping (optional)

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.

context