Master Jenkins Pipelines: Declarative vs Scripted Explained with Real Examples

What Is a Jenkins Pipeline

Jenkins supports two pipeline types: Declarative Pipeline and Scripted Pipeline. Scripted pipelines are used in older Jenkins versions, while the newer Jenkins releases recommend using Declarative pipelines. The documentation primarily describes Declarative pipelines.

Declarative Pipeline

In Declarative syntax, the pipeline process is defined inside a pipeline {} block, and the pipeline block contains all the work to be performed.

Key Parameters

agent any : Execute the pipeline on any available agent (or specify a particular node).

stage : Define a pipeline stage (e.g., Build, Test, Deploy). The name is user‑defined.

steps : Execute the specific commands for a stage.

// Jenkinsfile (Declarative Pipeline)
pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        echo 'Build'
      }
    }
    stage('Test') {
      steps {
        echo 'Test'
      }
    }
    stage('Deploy') {
      steps {
        echo 'Deploy'
      }
    }
  }
}

Scripted Pipeline

Scripted pipelines use one or more node blocks to run the core work of the pipeline.

node : Execute the pipeline (or any stage) on any available agent, or specify a concrete node.

stage : Similar to Declarative, but optional; defining a stage makes the UI display each stage separately.

// Jenkinsfile (Scripted Pipeline)
node {
  stage('Build') {
    echo 'Build'
  }
  stage('Test') {
    echo 'Test'
  }
  stage('Deploy') {
    echo 'Deploy'
  }
}

Sections

Sections are code blocks that may contain one or more Agent , Stages , post , Directives , and Steps .

1.1 Agent

The agent defines where the pipeline or a specific stage runs. It must be declared at the top level of the pipeline block, but can also be re‑defined inside a stage (optional).

any : Run on any available agent.

pipeline {
  agent any
}

none : No global agent; each stage must define its own agent.

pipeline {
  agent none
  stages {
    stage('Stage For Build') {
      agent any
    }
  }
}

label : Choose a specific node by label.

agent { label 'my-defined-label' }

node : Similar to label but can include extra configuration such as customWorkspace.

pipeline {
  agent none
  stages {
    stage('Stage For Build') {
      agent {
        node {
          label 'role-master'
          customWorkspace "/tmp/zhangzhuo/data"
        }
      }
      steps { sh "echo role-master > 1.txt" }
    }
  }
}

dockerfile : Build a container from a Dockerfile in the source repository.

agent {
  dockerfile {
    filename 'Dockerfile.build'
    dir 'build'
    label 'role-master'
    additionalBuildArgs '--build-arg version=1.0.2'
  }
}

docker : Use an external Docker image directly.

agent {
  docker {
    image '192.168.10.15/kubernetes/alpine:latest'
    label 'role-master'
    args '-v /tmp:/tmp'
  }
}

kubernetes : Requires the Kubernetes plugin. Example configuration creates a dynamic slave pod.

agent {
  kubernetes {
    cloud 'kubernetes'
    slaveConnectTimeout 1200
    workspaceVolume emptyDirWorkspaceVolume()
    yaml '''
kind: Pod
metadata:
  name: jenkins-agent
spec:
  containers:
  - args: ['$JENKINS_SECRET', '$JENKINS_NAME']
    image: '192.168.10.15/kubernetes/jnlp:alpine'
    name: jnlp
    imagePullPolicy: IfNotPresent
  - command:
    - "cat"
    image: "192.168.10.15/kubernetes/alpine:latest"
    name: "date"
    tty: true
  restartPolicy: Never
''' 
  }
}

1.2 Post

The post section runs after the pipeline finishes, handling actions such as notifications. It can be placed at the pipeline level or inside a stage. Supported conditions include: always: Run regardless of the build result. changed: Run only if the current result differs from the previous run. fixed: Run when the current build succeeds after a previous failure. regression: Run when the current build fails after a previous success. failure: Run only on failure. success: Run only on success. unstable: Run on unstable builds. aborted: Run when the build is manually aborted. unsuccessful: Run when the result is not success. cleanup: Run after all other post actions, regardless of result.

// Jenkinsfile (Declarative Pipeline)
pipeline {
  agent any
  stages {
    stage('Example1') { steps { echo 'Hello World1' } }
    stage('Example2') { steps { echo 'Hello World2' } }
  }
  post {
    always { echo 'I will always say Hello again!' }
  }
}

1.3 Steps

Steps execute one or more commands within a stage, such as echo or sh.

// Jenkinsfile (Declarative Pipeline)
pipeline {
  agent any
  stages {
    stage('Example') {
      steps {
        echo 'Hello World'
        sh '''
          echo 'Hello World1'
          echo 'Hello World2'
        '''
      }
    }
  }
}

2 Directives

Directives provide additional configuration for stages, such as environment variables, options, parameters, triggers, input, and when conditions.

2.1 Environment

Environment variables can be defined globally in the pipeline or locally within a stage. The credentials() function allows secure access to stored secrets.

// Example
pipeline {
  agent any
  environment {
    NAME = 'zhangzhuo'
  }
  stages {
    stage('env1') {
      environment { HARBOR = 'https://192.168.10.15' }
      steps { sh "env" }
    }
    stage('env2') { steps { sh "env" } }
  }
}

2.2 Options

Common pipeline options include buildDiscarder, disableConcurrentBuilds, disableResume, newContainerPerStage, quietPeriod, retry, timeout, and timestamps.

pipeline {
  agent any
  options {
    timeout(time: 1, unit: 'HOURS')
    timestamps()
    buildDiscarder(logRotator(numToKeepStr: '3'))
    quietPeriod(10)
    retry(3)
  }
  stages {
    stage('env1') { steps { sh "env"; sleep 2 } }
    stage('env2') { steps { sh "env" } }
  }
}

2.3 Parameters

Parameters let users provide input when triggering a pipeline. Supported types: string, text, booleanParam, choice, password, plus plugin‑provided types such as imageTag and gitParameter.

pipeline {
  agent any
  parameters {
    string(name: 'DEPLOY_ENV', defaultValue: 'staging', description: '1')
    text(name: 'DEPLOY_TEXT', defaultValue: 'One
Two
Three
', description: '2')
    booleanParam(name: 'DEBUG_BUILD', defaultValue: true, description: '3')
    choice(name: 'CHOICES', choices: ['one','two','three'], description: '4')
    password(name: 'PASSWORD', defaultValue: 'SECRET', description: 'A secret password')
    imageTag(name: 'DOCKER_IMAGE', image: 'kubernetes/kubectl', registry: 'https://192.168.10.15', credentialId: 'harbor-account')
    gitParameter(name: 'BRANCH', branchFilter: 'origin/(.*)', type: 'PT_BRANCH')
  }
  stages {
    stage('env1') { steps { sh "env" } }
    stage('git') { steps { git branch: "$BRANCH", credentialsId: 'gitlab-key', url: '[email protected]:root/env.git' } }
  }
}

2.4 Triggers

Triggers automate pipeline execution via cron, upstream jobs, SCM polling, etc.

pipeline {
  agent any
  triggers {
    cron('H */4 * * 1-5')   // Every 4 hours on weekdays
    cron('H/12 * * * *')     // Every 12 minutes
    cron('H * * * *')        // Every hour
  }
  stages { stage('Example') { steps { echo 'Hello World' } } }
}

2.5 Input

The input step enables interactive prompts during a pipeline run.

pipeline {
  agent any
  stages {
    stage('Example') {
      input {
        message "Continue?"
        ok "Proceed"
        submitter "alice,bob"
        parameters { string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?') }
      }
      steps { echo "Hello, ${PERSON}, nice to meet you." }
    }
  }
}

2.6 When

The when directive controls stage execution based on conditions such as branch, environment, expression, tag, etc.

pipeline {
  agent any
  stages {
    stage('Example Deploy') {
      when { branch 'main' }
      steps { echo 'Deploying' }
    }
    stage('Conditional Deploy') {
      when {
        allOf {
          branch 'master'
          environment name: 'DEPLOY_TO', value: 'production'
        }
      }
      steps { echo 'Deploying' }
    }
    stage('Expression Deploy') {
      when { expression { return params.DEBUG_BUILD } }
      steps { echo 'Deploying' }
    }
  }
}

2.7 Parallel

Parallel stages allow concurrent execution of multiple branches.

pipeline {
  agent any
  stages {
    stage('Non-Parallel Stage') { steps { echo 'This stage will be executed first.' } }
    stage('Parallel Stage') {
      failFast true
      parallel {
        stage('Branch A') { steps { echo 'On Branch A' } }
        stage('Branch B') { steps { echo 'On Branch B' } }
        stage('Branch C') {
          stages {
            stage('Nested 1') { steps { echo 'In stage Nested 1 within Branch C' } }
            stage('Nested 2') { steps { echo 'In stage Nested 2 within Branch C' } }
          }
        }
      }
    }
  }
}

Jenkinsfile Usage

Storing a Jenkinsfile in the source repository provides benefits such as versioned pipeline code, auditability, and collaborative editing.

1. Environment Variables

Jenkins provides many built‑in environment variables (e.g., BUILD_ID, BUILD_NUMBER, BUILD_TAG, BUILD_URL, JOB_NAME, NODE_NAME, JENKINS_URL, WORKSPACE). They can be accessed via env.VAR_NAME.

pipeline {
  agent any
  stages {
    stage('Print Env') {
      parallel {
        stage('BUILD_ID') { steps { echo "$env.BUILD_ID" } }
        stage('BUILD_NUMBER') { steps { echo "$env.BUILD_NUMBER" } }
        stage('BUILD_TAG') { steps { echo "$env.BUILD_TAG" } }
      }
    }
  }
}

2. Credential Management

Jenkins supports credentials() for secret text, username/password, and secret files.

Secret Text : Assign to environment variables for services like AWS.

pipeline {
  agent any
  environment {
    AWS_ACCESS_KEY_ID = credentials('txt1')
    AWS_SECRET_ACCESS_KEY = credentials('txt2')
  }
  stages { stage('Example') { steps { echo "$AWS_ACCESS_KEY_ID" } } }
}

Username/Password : Generates three variables – the combined USER:PASS, _USR, and _PSW.

pipeline {
  agent any
  environment { BITBUCKET_COMMON_CREDS = credentials('harbor-account') }
  stages { stage('printenv') { steps { sh "env" } } }
}

Secret File : Example using a Kubernetes kubeconfig file.

pipeline {
  agent {
    kubernetes {
      cloud 'kubernetes'
      slaveConnectTimeout 1200
      workspaceVolume emptyDirWorkspaceVolume()
      yaml '''
kind: Pod
metadata:
  name: jenkins-agent
spec:
  containers:
  - args: ['$JENKINS_SECRET', '$JENKINS_NAME']
    image: '192.168.10.15/kubernetes/jnlp:alpine'
    name: jnlp
    imagePullPolicy: IfNotPresent
  - command:
    - "cat"
    image: "192.168.10.15/kubernetes/kubectl:apline"
    name: "kubectl"
    tty: true
  restartPolicy: Never
''' 
    }
  }
  environment { MY_KUBECONFIG = credentials('kubernetes-cluster') }
  stages { stage('kubectl') { steps { container(name: 'kubectl') { sh "kubectl get pod -A --kubeconfig $MY_KUBECONFIG" } } } }
}

Storing the Jenkinsfile in version control enables review, audit, and collaborative editing of the pipeline definition.