# Declarative pipeline

## **What is Declarative Pipeline?**

Jenkins Pipeline execution engine supports two DSL syntaxes: Scripted Pipeline and Declarative Pipeline. Scripted Pipeline allows users to code their Pipelines using a Groovy DSL. Declarative Pipeline replaces Groovy variable assignments, control structures, loops, and exception handling with a predefined structure and model to allow users of all experience levels to quickly create consistent, concise Pipelines without learning Groovy.

## All valid Declarative Pipelines must be enclosed within a `pipeline` block, for example:

```plaintext
pipeline {

    /* insert Declarative Pipeline here */
}
```

## The basic statements and expressions which are valid in Declarative Pipeline follow the same rules as [Groovy’s syntax](http://groovy-lang.org/syntax.html) with the following exceptions:

* The top-level of the Pipeline must be a *block*, specifically: `pipeline { }`.
    
* No semicolons as statement separators. Each statement has to be on its own line.
    
* Blocks must only consist of [Sections](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-sections), [Directives](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-directives), [Steps](https://www.jenkins.io/doc/book/pipeline/syntax/#declarative-steps), or assignment statements.
    
* A property reference statement is treated as a no-argument method invocation. So, for example, `input` is treated as `input()`.
    

## **Pipeline Fundamentals**

In its simplest form, a Pipeline will automatically check out the code in the same repository that contains the Jenkinsfile, run on an agent and be grouped into stages that contain steps defining specific actions. All Declarative Pipelines must start with pipeline and include these 4 directives to be syntactically correct: agent, stages, stage, and steps. These will be described in more detail in following sections. The following is an example of a bare minimum Pipeline:

```plaintext
 pipeline {
    agent any
    stages {
        stage(‘Build’) {
            steps {
                sh 'npm --version'
            }
        }
    }
}
```

## **Complete Syntax Reference**

***pipeline (required)*** -  contains the entire Pipeline definition

***agent (required)***\- defines the agent used for entire pipeline or a stage

* ***any* -** use any available agent
    
* ***none*** - do not use a node
    
* ***node*** -  allocate a specific executor
    
    * ***label -*** existing Jenkins node label for agent
        
    * ***customWorkspace*** - use a custom workspace directory on agent
        
* ***docker*** - requires docker-enabled node
    
    * ***image -*** run inside specified docker image
        
    * ***label*** -  existing Jenkins node label for agent
        
    * ***registryUrl*** - use a private registry hosting image
        
    * ***registryCredentialsId*** - id of credentials to connect to registry
        
    * ***reuseNode*** - (Boolean) reuse the workspace and node allocated previously
        
    * ***args*** -  arguments for docker container.
        
    * ***customWorkspace*** - use a custom workspace directory on agent
        
* ***dockerfile*** - use a local dockerfile
    
    * ***filename -*** name of local dockerfile
        
    * ***dir*** - subdirectory to use
        
    * ***label*** -  existing Jenkins node label
        
    * ***reuseNode*** - (Boolean) reuse the workspace and node allocated previously
        
    * ***args*** -  arguments for docker container
        
    * ***customWorkspace*** - use a custom workspace directory on agent
        

***stages (required)*** - contains all stages and steps within Pipeline

***stage (required)*** \- specific named  “Stage” of the Pipeline

* ***steps (required)*** - build steps that define the actions in the stage. Contains one or more of following:
    
    * any build step or build wrapper defined in Pipeline. e.g. ***sh, bat, powershell, timeout, retry, echo, archive, junit***, etc.
        
    * ***script***  - execute Scripted Pipeline block
        
* ***when***  - executes stage conditionally
    
    * ***branch*** - stage runs when branch name matches ant pattern
        
    * ***expression*** - Boolean Groovy expression
        
    * ***anyOf*** \- any of the enclosed conditions are true
        
    * ***allOf*** - all of the enclosed conditions are true
        
    * ***not*** - none of the enclosed conditions are true
        
* ***parallel*  -**
    
    * ***stage***\- stages are executed in parallel but
        
* ***agent***, ***environment***, ***tools*** and ***post*** may also optionally be defined in ***stage***           
    

***environment*** - a sequence of “key = value” pairs to define environment variables

* ***credentials(‘<id>’)*** (optional) - Bind credentials to variable.
    

***libraries*** - load shared libraries from an scm

* ***lib*** - the name of the shared library to load
    

***options*** - options for entire Pipeline.

* ***skipDefaultCheckout*** - disable auto checkout scm
    
* ***timeout*** \- sets timeout for entire Pipeline
    
* ***buildDiscarder*** - discard old builds
    
* ***disableConcurrentBuilds*** - disable concurrent Pipeline runs
    
* ***ansiColor*** - color the log file output
    

***tools*** - Installs predefined tools to be available on PATH

***triggers*** - triggers to launch Pipeline based on schedule, etc.

***parameters*** - parameters that are prompted for at run time.

***post*** - defines actions to be taken when ***pipeline*** or ***stage*** completes based on outcome. Conditions execute in order:

* ***always*** - run regardless of Pipeline status.
    
* ***changed*** - run if the result of Pipeline has changed from last run
    
* ***success*** - run if Pipeline is successful
    
* ***unstable*** - run if Pipeline result is unstable
    
* ***failure*** - run if the Pipeline has failed
    
    ## **Example of scripts**
    
    *Example 1. Docker Agent, Declarative Pipeline*
    
* ```plaintext
    pipeline {
        agent { docker 'maven:3.9.0-eclipse-temurin-11' } 
        stages {
            stage('Example Build') {
                steps {
                    sh 'mvn -B clean verify'
                }
            }
        }
    }
    ```
    
    *Example 2. Stage-level Agent Section*
    
* ```plaintext
    pipeline {
        agent none 
        stages {
            stage('Example Build') {
                agent { docker 'maven:3.9.0-eclipse-temurin-11' } 
                steps {
                    echo 'Hello, Maven'
                    sh 'mvn --version'
                }
            }
            stage('Example Test') {
                agent { docker 'openjdk:8-jre' } 
                steps {
                    echo 'Hello, JDK'
                    sh 'java -version'
                }
            }
        }
    }
    ```