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:

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:

• 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, Directives, 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:

 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

•   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

•   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'
                }
            }
        }
    }