Master Jenkins Declarative & Scripted Pipelines: Full Guide with Real‑World Examples

1. What Is a Pipeline

Jenkins defines two pipeline syntaxes: Declarative Pipeline (recommended for new jobs) and Scripted Pipeline (used in older Jenkins versions). Both describe a series of stages that run on agents.

2. Declarative Pipeline

In a declarative pipeline the top‑level pipeline{} block contains a agent, stages, and optional post. The agent determines where the pipeline or each stage runs. Common values are any (any available executor), none (no global agent, each stage must define its own), label 'my-label', or a docker / dockerfile definition.

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

The post block runs after the pipeline finishes. Conditions such as always, success, failure, unstable, changed, fixed, regression, aborted, cleanup, and unsuccessful control when the steps are executed.

pipeline {
  agent any
  stages { /* … */ }
  post {
    always { echo 'I will always say Hello again!' }
  }
}

3. Scripted Pipeline

A scripted pipeline uses a node block to allocate an executor and then defines stages manually. The syntax is more free‑form but requires explicit node allocation.

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

4. Agent Variants

any : run on any available executor.

none : no global agent; each stage must declare its own.

label : select a node with a specific label, e.g. agent { label 'my-defined-label' }.

node : similar to label</strong> but can also set <code>customWorkspace.

dockerfile : build a Docker image from a Dockerfile in the repository and run the stage inside that container.

docker : run the stage in an existing Docker image, e.g. agent { docker 'maven:3-alpine' }.

kubernetes : launch a pod on a Kubernetes cluster; the yaml field can contain a full pod definition.

5. Post Conditions

The post section can be placed at the pipeline level or inside an individual stage. It allows you to send notifications, archive artifacts, or clean up resources based on the build result.

pipeline {
  agent any
  stages { /* … */ }
  post {
    always { echo 'Always run' }
    success { echo 'Success only' }
    failure { echo 'Failure only' }
  }
}

6. Parameters

Parameters let users supply values when manually triggering a build. They are defined in a top‑level parameters block and can be of type string, text, booleanParam, choice, or password. Plugin‑provided types such as imageTag and gitParameter are also supported.

pipeline {
  agent any
  parameters {
    string(name: 'DEPLOY_ENV', defaultValue: 'staging')
    booleanParam(name: 'DEBUG_BUILD', defaultValue: true)
    choice(name: 'CHOICES', choices: ['one','two','three'])
    password(name: 'PASSWORD', defaultValue: 'SECRET')
  }
  stages { /* … */ }
}

7. Options

Options affect the whole pipeline or a single stage. Common directives include timeout, timestamps, buildDiscarder, quietPeriod, retry, disableConcurrentBuilds, and disableResume. Stage‑level options can only use timeout, retry, timestamps, or skipDefaultCheckout.

pipeline {
  agent any
  options {
    timeout(time: 1, unit: 'HOURS')
    timestamps()
    buildDiscarder(logRotator(numToKeepStr: '3'))
    quietPeriod(10)
    retry(3)
  }
  stages { /* … */ }
}

8. Triggers

Automatic execution can be configured with triggers. Supported types are cron (periodic schedules), upstream (run after another job finishes), pollSCM, and webhooks. The cron syntax uses H to spread load across the hour.

pipeline {
  agent any
  triggers { cron('H */4 * * 1-5') }
  stages { /* … */ }
}

9. Input

The input step pauses the pipeline and asks a user for confirmation or additional data. It supports message, id, ok, submitter, and a list of parameters.

pipeline {
  agent any
  stages {
    stage('Approve') {
      input {
        message "Proceed?"
        ok "Yes"
        submitter "alice,bob"
        parameters { string(name: 'PERSON', defaultValue: 'Mr Jenkins') }
      }
      steps { echo "Hello, ${PERSON}" }
    }
  }
}

10. When Conditions

The when directive decides whether a stage runs. Conditions can be combined with not, allOf, or anyOf. Built‑in conditions include branch, changelog, environment, equals, expression, tag, and more.

pipeline {
  agent any
  stages {
    stage('Deploy') {
      when { branch 'main' }
      steps { echo 'Deploying' }
    }
  }
}

Advanced usage can evaluate conditions before allocating an agent by setting beforeAgent true inside the when block.

11. Parallel Execution

Parallel branches are defined with the parallel keyword. The failFast flag stops all branches as soon as one fails.

pipeline {
  agent any
  stages {
    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 'Nested 1' } }
            stage('Nested 2') { steps { echo 'Nested 2' } }
          }
        }
      }
    }
  }
}

12. Environment Variables

Jenkins provides built‑in environment variables such as BUILD_ID, BUILD_NUMBER, BUILD_TAG, BUILD_URL, JOB_NAME, NODE_NAME, JENKINS_URL, and WORKSPACE. They can be accessed via env.VAR_NAME.

pipeline {
  agent any
  stages {
    stage('Print Env') {
      steps {
        echo "BUILD_ID = ${env.BUILD_ID}"
        echo "JOB_NAME = ${env.JOB_NAME}"
      }
    }
  }
}

13. Dynamic Variables

Shell steps can return their output or exit status. Use returnStdout: true to capture output (trim trailing newline) and returnStatus: true to capture the exit code.

pipeline {
  agent any
  environment {
    CC = "${sh(returnStdout: true, script: 'echo -n clang')}"
    EXIT_STATUS = "${sh(returnStatus: true, script: 'exit 1')}"
  }
  stages { /* … */ }
}

14. Credential Management

Jenkins’ credentials() function injects secret text, username/password pairs, or secret files into the pipeline. For secret text you get a single variable; for username/password you receive three variables: the combined NAME, NAME_USR, and NAME_PSW.

// Secret‑text example
pipeline {
  agent any
  environment {
    AWS_ACCESS_KEY_ID = credentials('txt1')
    AWS_SECRET_ACCESS_KEY = credentials('txt2')
  }
  stages { /* … */ }
}

// Username/password example
pipeline {
  agent any
  environment {
    BITBUCKET_CREDS = credentials('harbor-account')
  }
  stages { /* … */ }
}

// Secret‑file (e.g., kubeconfig) example
pipeline {
  agent { kubernetes { /* pod yaml */ } }
  environment { MY_KUBECONFIG = credentials('kubernetes-cluster') }
  stages {
    stage('kubectl') {
      steps {
        container('kubectl') {
          sh "kubectl get pod -A --kubeconfig $MY_KUBECONFIG"
        }
      }
    }
  }
}