Master Jenkins Declarative and Scripted Pipelines: A Complete Guide

1. What Is a Jenkins Pipeline

Jenkins supports two pipeline syntaxes: Declarative Pipeline (recommended for new pipelines) and Scripted Pipeline (used in older Jenkins versions). Both define the entire build process inside a pipeline{} block.

2. Declarative Pipeline

In a declarative pipeline the top‑level pipeline block contains optional agent, stages, post, environment, options, parameters, triggers, and other directives.

2.1 Agent

The agent defines where the pipeline or a specific stage runs. Common values are: any – run on any available executor. none – no global agent; each stage must define its own. label 'my-label' – run on nodes with the given label. node { label 'my-label' } – same as label but allows additional configuration such as customWorkspace. dockerfile { filename 'Dockerfile.build' } – build a Docker image from a Dockerfile in the workspace. docker { image 'maven:3-alpine' } – run steps inside a pre‑built Docker image. kubernetes { ... } – run on a Kubernetes pod; requires the Kubernetes plugin.

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

2.2 Stages and Steps

Each stage groups related steps. steps can contain shell commands ( sh) or other pipeline steps.

// Using sh to run multiple commands
pipeline {
  agent any
  stages {
    stage('Example') {
      steps {
        sh """
          echo 'Hello World1'
          echo 'Hello World2'
        """
      }
    }
  }
}

2.3 Post Actions

The post block runs after a pipeline or stage finishes. Supported conditions include always, changed, fixed, failure, success, unstable, aborted, and cleanup.

// Post example
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!' }
  }
}

2.4 Parameters

Parameters let users supply values when triggering a build. Types include string, text, booleanParam, choice, password, and plugin‑provided types such as imageTag and gitParameter.

// Parameter example
pipeline {
  agent any
  parameters {
    string(name: 'DEPLOY_ENV', defaultValue: 'staging')
    text(name: 'DEPLOY_TEXT', defaultValue: 'One
Two
Three')
    booleanParam(name: 'DEBUG_BUILD', defaultValue: true)
    choice(name: 'CHOICES', choices: ['one','two','three'])
    password(name: 'PASSWORD', defaultValue: 'SECRET')
    imageTag(name: 'DOCKER_IMAGE', image: 'kubernetes/kubectl')
    gitParameter(name: 'BRANCH')
  }
  stages {
    stage('env1') { steps { sh "env" } }
    stage('git') { steps { git branch: "$BRANCH", url: '[email protected]:root/env.git' } }
  }
}

2.5 Triggers

Automatic pipeline execution can be configured with triggers such as cron, upstream, and pollSCM. Cron expressions use H to spread load.

// Cron trigger example
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.6 Conditional Execution (when)

The when directive controls whether a stage runs based on conditions such as branch name, environment variable, expression, tag, or logical combinations ( not, allOf, anyOf). Pre‑conditions like beforeAgent can evaluate the condition before allocating an agent.

// When example with branch condition
pipeline {
  agent any
  stages {
    stage('Deploy') {
      when { branch 'main' }
      steps { echo 'Deploying' }
    }
  }
}

2.7 Parallel Execution

Parallel stages run concurrently. The failFast option aborts remaining branches if any fails.

// Parallel example
pipeline {
  agent any
  stages {
    stage('Non-Parallel') { steps { echo 'First stage' } }
    stage('Parallel') {
      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 Nested 1' } }
            stage('Nested 2') { steps { echo 'In Nested 2' } }
          }
        }
      }
    }
  }
}

3. Jenkinsfile Usage

Storing the Jenkinsfile in source control enables versioning, peer review, and collaboration. The file can be placed in any repository and referenced by Jenkins jobs.

3.1 Built‑in Environment Variables

Jenkins provides many read‑only variables accessible via env.VARIABLE_NAME, such as BUILD_ID, BUILD_NUMBER, BUILD_TAG, BUILD_URL, JOB_NAME, NODE_NAME, JENKINS_URL, and WORKSPACE.

// Print selected environment variables
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}" } }
      }
    }
  }
}

3.2 Dynamic Variables

Shell commands can return output or exit status to set pipeline variables using returnStdout:true or returnStatus:true.

// Dynamic variable example
pipeline {
  agent any
  environment {
    CC = "${sh(returnStdout: true, script: 'echo -n clang').trim()}"
    EXIT_STATUS = "${sh(returnStatus: true, script: 'exit 1')}"
  }
  stages { stage('Show') { steps { echo "CC=$CC, status=$EXIT_STATUS" } } }
}

3.3 Credential Management

Credentials can be injected as environment variables using the credentials() function. Types include secret text, username/password, and secret files.

// Secret text credentials
pipeline {
  agent any
  environment {
    AWS_ACCESS_KEY_ID = credentials('txt1')
    AWS_SECRET_ACCESS_KEY = credentials('txt2')
  }
  stages { stage('Print') { steps { echo "Key=$AWS_ACCESS_KEY_ID" } } }
}

// Username/password credentials
pipeline {
  agent any
  environment {
    BITBUCKET_CREDS = credentials('harbor-account')
  }
  stages { stage('Print') { steps { sh "env" } } }
}

// Secret file (e.g., kubeconfig)
pipeline {
  agent {
    kubernetes {
      yaml '''
        kind: Pod
        spec:
          containers:
            - name: jnlp
              image: 192.168.10.15/kubernetes/jnlp:alpine
            - name: kubectl
              image: 192.168.10.15/kubernetes/kubectl:alpine
          restartPolicy: Never
      '''
    }
  }
  environment {
    MY_KUBECONFIG = credentials('kubernetes-cluster')
  }
  stages {
    stage('kubectl') {
      steps {
        container('kubectl') {
          sh "kubectl get pod -A --kubeconfig $MY_KUBECONFIG"
        }
      }
    }
  }
}

Reference URL: https://github.com/jenkinsci/kubernetes-plugin/