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: Nodes and Processes

bat: Windows Batch Script

  • script : String
    Executes a Batch script. Multiple lines allowed. When using the returnStdout flag, you probably wish to prefix this with @, lest the command itself be included in the output.
  • encoding : String (optional)
    Encoding of process output. In the case of returnStdout, applies to the return value of this step; otherwise, or always for standard error, controls how text is copied to the build log. If unspecified, uses the system default encoding of the node on which the step is run. If there is any expectation that process output might include non-ASCII characters, it is best to specify the encoding explicitly. For example, if you have specific knowledge that a given process is going to be producing UTF-8 yet will be running on a node with a different system encoding (typically Windows, since every Linux distribution has defaulted to UTF-8 for a long time), you can ensure correct output by specifying: encoding: 'UTF-8'
  • label : String (optional)
    Label to be displayed in the pipeline step view and blue ocean details for the step instead of the step type. So the view is more meaningful and domain specific instead of technical.
  • returnStatus : boolean (optional)
    Normally, a script which exits with a nonzero status code will cause the step to fail with an exception. If this option is checked, the return value of the step will instead be the status code. You may then compare it to zero, for example.
  • returnStdout : boolean (optional)
    If checked, standard output from the task is returned as the step value as a String, rather than being printed to the build log. (Standard error, if any, will still be printed to the log.) You will often want to call .trim() on the result to strip off a trailing newline.

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 : String
    The relative path of the directory in the workspace to use as a new working directory.

node: Allocate node

Allocates an executor on a node (typically a build agent) and runs further code in the context of a workspace on that agent.
  • label : String
    Computer name, label name, or any other label expression like linux && 64bit to restrict where this step builds. May be left blank, in which case any available executor is taken.

    Supported operators

    The following operators are supported, in descending order of precedence:
    (expression)
    parentheses — used to explicitly define the associativity of an expression
    !expression
    NOT — negation; the result of expression must not be true
    a && b
    AND — both of the expressions a and b must be true
    a || b
    OR — either of the expressions a or b may be true
    a -> b
    "implies" operator — equivalent to !a || b.
    For example, windows -> x64 could be thought of as "if a Windows agent is used, then that agent must be 64-bit", while still allowing this block to be executed on any agents that do not have the windows label, regardless of whether they have also have an x64 label
    a <-> b
    "if and only if" operator — equivalent to a && b || !a && !b
    For example, windows <-> dc2 could be thought of as "if a Windows agent is used, then that agent must be in datacenter 2, but if a non-Windows agent is used, then it must not be in datacenter 2"

    Notes

    • All operators are left-associative, i.e. a -> b -> c is equivalent to (a -> b) -> c.
    • Labels or agent names can be surrounded with quotation marks if they contain characters that would conflict with the operator syntax.
      For example, "osx (10.11)" || "Windows Server".
    • Expressions can be written without whitespace, but including it is recommended for readability; Jenkins will ignore whitespace when evaluating expressions.
    • Matching labels or agent names with wildcards or regular expressions is not supported.
    • An empty expression will always evaluate to true, matching all agents.

    Examples

    master
    This block may be executed only on the Jenkins built-in node
    linux-machine-42
    This block may be executed only on the agent with the name linux-machine-42 (or on any machine that happens to have a label called linux-machine-42)
    windows && jdk9
    This block may be executed only on any Windows agent that has version 9 of the Java Development Kit installed (assuming that agents with JDK 9 installed have been given a jdk9 label)
    postgres && !vm && (linux || freebsd)
    This block may be executed only any on Linux or FreeBSD agent, so long as they are not a virtual machine, and they have PostgreSQL installed (assuming that each agent has the appropriate labels — in particular, each agent running in a virtual machine must have the vm label in order for this example to work as expected)

powershell: Windows PowerShell Script

  • script : String
    Executes a Windows PowerShell script (version 3 or later). Multiple lines allowed.
    Note: be aware of the differences between Windows PowerShell and PowerShell Core, check which one is available on your agents.
  • encoding : String (optional)
    Encoding of process output. In the case of returnStdout, applies to the return value of this step; otherwise, or always for standard error, controls how text is copied to the build log. If unspecified, uses the system default encoding of the node on which the step is run. If there is any expectation that process output might include non-ASCII characters, it is best to specify the encoding explicitly. For example, if you have specific knowledge that a given process is going to be producing UTF-8 yet will be running on a node with a different system encoding (typically Windows, since every Linux distribution has defaulted to UTF-8 for a long time), you can ensure correct output by specifying: encoding: 'UTF-8'
  • label : String (optional)
    Label to be displayed in the pipeline step view and blue ocean details for the step instead of the step type. So the view is more meaningful and domain specific instead of technical.
  • returnStatus : boolean (optional)
    Normally, a script which exits with a nonzero status code will cause the step to fail with an exception. If this option is checked, the return value of the step will instead be the status code. You may then compare it to zero, for example.
  • returnStdout : boolean (optional)
    If checked, standard output from the task is returned as the step value as a String, rather than being printed to the build log. (Standard error, if any, will still be printed to the log.) You will often want to call .trim() on the result to strip off a trailing newline.

pwsh: PowerShell Core Script

  • script : String
    Executes a PowerShell script. Multiple lines allowed. This plugin supports PowerShell Core 6+.
    Note: be aware of the differences between Windows PowerShell and PowerShell Core, check which one is available on your agents.
  • encoding : String (optional)
    Encoding of process output. In the case of returnStdout, applies to the return value of this step; otherwise, or always for standard error, controls how text is copied to the build log. If unspecified, uses the system default encoding of the node on which the step is run. If there is any expectation that process output might include non-ASCII characters, it is best to specify the encoding explicitly. For example, if you have specific knowledge that a given process is going to be producing UTF-8 yet will be running on a node with a different system encoding (typically Windows, since every Linux distribution has defaulted to UTF-8 for a long time), you can ensure correct output by specifying: encoding: 'UTF-8'
  • label : String (optional)
    Label to be displayed in the pipeline step view and blue ocean details for the step instead of the step type. So the view is more meaningful and domain specific instead of technical.
  • returnStatus : boolean (optional)
    Normally, a script which exits with a nonzero status code will cause the step to fail with an exception. If this option is checked, the return value of the step will instead be the status code. You may then compare it to zero, for example.
  • returnStdout : boolean (optional)
    If checked, standard output from the task is returned as the step value as a String, rather than being printed to the build log. (Standard error, if any, will still be printed to the log.) You will often want to call .trim() on the result to strip off a trailing newline.

sh: Shell Script

  • script : String

    Runs a Bourne shell script, typically on a Unix node. Multiple lines are accepted.

    An interpreter selector may be used, for example: #!/usr/bin/perl

    Otherwise the system default shell will be run, using the -xe flags (you can specify set +e and/or set +x to disable those).

  • encoding : String (optional)
    Encoding of process output. In the case of returnStdout, applies to the return value of this step; otherwise, or always for standard error, controls how text is copied to the build log. If unspecified, uses the system default encoding of the node on which the step is run. If there is any expectation that process output might include non-ASCII characters, it is best to specify the encoding explicitly. For example, if you have specific knowledge that a given process is going to be producing UTF-8 yet will be running on a node with a different system encoding (typically Windows, since every Linux distribution has defaulted to UTF-8 for a long time), you can ensure correct output by specifying: encoding: 'UTF-8'
  • label : String (optional)
    Label to be displayed in the pipeline step view and blue ocean details for the step instead of the step type. So the view is more meaningful and domain specific instead of technical.
  • returnStatus : boolean (optional)
    Normally, a script which exits with a nonzero status code will cause the step to fail with an exception. If this option is checked, the return value of the step will instead be the status code. You may then compare it to zero, for example.
  • returnStdout : boolean (optional)
    If checked, standard output from the task is returned as the step value as a String, rather than being printed to the build log. (Standard error, if any, will still be printed to the log.) You will often want to call .trim() on the result to strip off a trailing newline.

ws: Allocate workspace

Allocates a workspace. Note that a workspace is automatically allocated for you with the node step.
  • dir : String

    A workspace is automatically allocated for you with the node step, or you can get an alternate workspace with this ws step, but by default the location is chosen automatically. (Something like AGENT_ROOT/workspace/JOB_NAME@2.)

    You can instead specify a path here and that workspace will be locked instead. (The path may be relative to the build agent root, or absolute.)

    If concurrent builds ask for the same workspace, a directory with a suffix such as @2 may be locked instead. Currently there is no option to wait to lock the exact directory requested; if you need to enforce that behavior, you can either fail (error) when pwd indicates that you got a different directory, or you may enforce serial execution of this part of the build by some other means such as stage name: '…', concurrency: 1.

    If you do not care about locking, just use the dir step to change current directory.


Was this page helpful?

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.