Understanding Jenkins Declarative Pipeline Syntax

Jenkins pipelines allow users to build a complete continuous delivery (CD) pipeline as part of their application code, storing build, test, and delivery steps in a Jenkinsfile . The declarative pipeline syntax provides a simple predefined hierarchy that is accessible to users of all experience levels.

The simplest form runs on an agent and contains stages, each with steps that define specific actions.

pipeline {
  agent {
    label ''
  }
  stages {
    stage('Build') {
      steps {
        sh 'mvn install'
      }
    }
  }
}

The declarative syntax also lets you control various aspects of the execution environment. For example, you can build a Java application with Maven inside a Docker container, limit the pipeline to the "master" branch, and set a six‑hour timeout.

pipeline {
  agent {
    docker {
      label 'docker-node'
      image 'maven'
      args '-v /tmp:/tmp -p 80:80'
    }
  }
  environment {
    GIT_COMMITTER_NAME = 'jenkins'
  }
  options {
    timeout(6, HOURS)
  }
  stages {
    stage('Build') {
      steps {
        sh 'mvn clean install'
      }
    }
    stage('Archive') {
      when {
        branch '*/master'
      }
      steps {
        archive '**/target/**/*'
        junit '**/target/surefire-reports/*.xml'
      }
    }
  }
  post {
    always {
      deleteDir()
    }
  }
}

Required Declarative Syntax

pipeline : defines a Jenkins pipeline.

agent : defines the node that executes pipeline stages. Options include label (node label) and docker (Docker‑based node) with sub‑options image and args .

stages : the collection of stages in the pipeline.

stage : a single stage within the pipeline.

steps : build steps such as sh , bat , timeout , echo , archive , junit , etc.

parallel : optional parallel steps.

script : execute a script block.

when : condition for running the stage (e.g., based on branch or variable).

agent, environment, tools, post : additional optional sections.

Optional Declarative Syntax

environment : defines environment variables for the pipeline.

options : defines pipeline runtime options such as skipDefaultCheckout , timeout , buildDiscarder , and disableConcurrentBuilds .

tools : makes pre‑installed tools available.

triggers : defines build triggers for the pipeline.

parameters : defines runtime parameters.

post : defines actions after pipeline execution, with conditions like always , success , and failure .

The author, Ze Yang, is a DevOps practitioner sharing enterprise‑level DevOps operations and development techniques, focusing on practical Linux and DevOps courses.