Declarative Pipeline is a relatively recent addition to Jenkins Pipeline [1] which presents a more simplified and opinionated syntax on top of the Pipeline sub-systems.
All valid Declarative Pipelines must be enclosed within a pipeline block, for example:
pipeline < /* insert Declarative Pipeline here */ >▼
The basic statements and expressions which are valid in Declarative Pipeline follow the same rules as Groovy’s syntax with the following exceptions:
Sections in Declarative Pipeline typically contain one or more declarative directives or declarative steps.
The post section defines actions which will be run at the end of the Pipeline run. A number of additional post conditions blocks are supported within the post section: always , changed , failure , success , and unstable . These blocks allow for the execution of steps at the tail-end of the Pipeline run, depending on the status of the Pipeline.
In the top-level pipeline block and each stage block.
Run regardless of the completion status of the Pipeline run.
Only run if the current Pipeline run has a different status from the previously completed Pipeline.
Only run if the current Pipeline has a "failed" status, typically denoted in the web UI with a red indication.
Only run if the current Pipeline has a "success" status, typically denoted in the web UI with a blue or green indication.
Only run if the current Pipeline has an "unstable" status, usually caused by test failures, code violations, etc. Typically denoted in the web UI with a yellow indication.
// Declarative // pipeline < agent any stages < stage('Example') < steps < echo 'Hello World' >> > post (1) always (2) echo 'I will always say Hello again!' > > > // Script //▼
| 1 | Conventionally, the post section should be placed at the end of the Pipeline. |
| 2 | The post conditions blocks can use steps. |
A sequence of one or more stage directives, the stages section is where the bulk of the "work" described by a Pipeline will be located. At a minimum it is recommended that stages contain at least one stage directive for each discrete part of the continuous delivery process, such as Build, Test, and Deploy.
Only once, inside the pipeline block.
// Declarative // pipeline (1) stage('Example') < steps < echo 'Hello World' >> > > // Script //▼
| 1 | The stages section will typically follow the directives such as agent , options , etc. |
Defines a series of steps to be executed in a given stage directive.
Inside each stage block.
// Declarative // pipeline (1) echo 'Hello World' > > > > // Script //▼
| 1 | The steps section must contain one or more steps. |
The agent directive specifies where the entire Pipeline, or a specific stage, will execute in the Jenkins environment depending on where the agent directive is placed. The directive must be defined at the top-level inside the pipeline block, but stage-level usage is optional.
In the top-level pipeline block and each stage block.
In order to support the wide variety of use-cases Pipeline authors may have, the agent directive supports a few different types of parameters. These parameters can be applied at the top-level of the pipeline block, or within each stage directive.
Execute the Pipeline, or stage, on any available agent. For example: agent any
When applied at the top-level of the pipeline block no global agent will be allocated for the entire Pipeline run and each stage directive will need to contain its own agent directive. For example: agent none
Execute the Pipeline, or stage, on an agent available in the Jenkins environment with the provided label. For example: agent
agent < node < label 'labelName' >> behaves the same as agent < label 'labelName' >, but node allows for additional options (such as customWorkspace ).
Execute the Pipeline, or stage, with the given container which will be dynamically provisioned on a node pre-configured to accept Docker-based Pipelines, or on a node matching the optionally defined label parameter. docker also optionally accepts an args parameter which may contain arguments to pass directly to a docker run invocation. For example: agent < docker 'maven:3-alpine' >or
dockerfileagent < docker < image 'maven:3-alpine' label 'my-defined-label' args '-v /tmp:/tmp' >>▼
Execute the Pipeline, or stage, with a container built from a Dockerfile contained in the source repository. Conventionally this is the Dockerfile in the root of the source repository: agent < dockerfile true >. If building a Dockerfile in another directory, use the dir option: agent < dockerfile < dir 'someSubDir' >> .
These are a few options for two or more agent implementations. They are not required unless explicitly stated.
A string. The label on which to run the Pipeline or individual stage .
This option is valid for node , docker and dockerfile , and is required for node .
customWorkspaceA string. Run the Pipeline or individual stage this agent is applied to within this custom workspace, rather than the default. It can be either a relative path, in which case the custom workspace will be under the workspace root on the node, or an absolute path. For example:
agent < node < label 'my-defined-label' customWorkspace '/some/other/path' >>▼
This option is valid for node , docker and dockerfile .
A boolean, false by default. If true, run the container in the node specified at the top-level of the Pipeline, in the same workspace, rather than on a new node entirely.
This option is valid for docker and dockerfile , and only has an effect when used on an agent for an individual stage .
// Declarative // pipeline < agent < docker 'maven:3-alpine' >(1) stages < stage('Example Build') < steps < sh 'mvn -B clean verify' >> > > // Script //▼
| 1 | Execute all the steps defined in this Pipeline within a newly created container of the given name and tag ( maven:3-alpine ). |
// Declarative // pipeline (1) stages < stage('Example Build') < agent < docker 'maven:3-alpine' >(2) steps < echo 'Hello, Maven' sh 'mvn --version' >> stage('Example Test') < agent < docker 'openjdk:8-jre' >(3) steps < echo 'Hello, JDK' sh 'java -version' >> > > // Script //▼
| 1 | Defining agent none at the top-level of the Pipeline ensures that executors will not be created unnecessarily. Using agent none requires that each stage directive contain an agent directive. |
| 2 | Execute the steps contained within this stage using the given container. |
| 3 | Execute the steps contained within this steps using a different image from the previous stage. |
The environment directive specifies a sequence of key-value pairs which will be defined as environment variables for the all steps, or stage-specific steps, depending on where the environment directive is located within the Pipeline.
This directive supports a special helper method credentials() which can be used to access pre-defined Credentials by their identifier in the Jenkins environment. For Credentials which are of type "Secret Text", the credentials() method will ensure that the environment variable specified contains the Secret Text contents. For Credentials which are of type "Standard username and password", the environment variable specified will be set to username:password and two additional environment variables will be automatically be defined: MYVARNAME_USR and MYVARNAME_PSW respective.