Understanding Jenkins Pipelines: Declarative vs Scripted, Agents, Stages, and Advanced Features

What Is a Pipeline

Jenkins supports two types of pipelines: Declarative Pipeline and Scripted Pipeline . Declarative pipelines are recommended for new versions, while scripted pipelines are the older style.

Declarative Pipeline

In a declarative pipeline, the entire process is defined inside a pipeline {} block. Key sections include agent , stages , steps , and optional post actions.

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

Scripted Pipeline

A scripted pipeline uses a node block to execute stages and steps.

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

Key Pipeline Elements

Agent

The agent defines where the pipeline or a specific stage runs. Options include any , none , label , docker , dockerfile , and kubernetes .

pipeline {
  agent any
}

pipeline {
  agent none
  stages {
    stage('Build') {
      agent { label 'my-node' }
      steps { echo 'Build' }
    }
  }
}

Stages and Steps

Each stage groups related steps. Steps can be simple commands like echo or shell scripts using sh .

stage('Example') {
  steps {
    sh """
      echo 'Hello World1'
      echo 'Hello World2'
    """
  }
}

Directives

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

Environment

Define global or stage‑level environment variables. Credentials can be injected using the credentials() function.

pipeline {
  agent any
  environment {
    KUBECONFIG = credentials('kubernetes-cluster')
  }
  stages { ... }
}

Options

Common options include timeout , retry , timestamps , and buildDiscarder .

pipeline {
  agent any
  options {
    timeout(time: 1, unit: 'HOURS')
    timestamps()
    buildDiscarder(logRotator(numToKeepStr: '3'))
    retry(3)
  }
  stages { ... }
}

Parameters

Parameters allow users to supply values when triggering a build (e.g., string , booleanParam , choice ).

pipeline {
  agent any
  parameters {
    string(name: 'DEPLOY_ENV', defaultValue: 'staging')
    booleanParam(name: 'DEBUG_BUILD', defaultValue: true)
  }
  stages { ... }
}

Triggers

Automate pipeline execution with cron , upstream , or SCM polling.

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

Input

Interactive prompts can be added to pause a pipeline and request user input.

stage('Approval') {
  input {
    message "Proceed?"
    ok "Yes"
    parameters { string(name: 'PERSON', defaultValue: 'User') }
  }
  steps { echo "Hello ${PERSON}" }
}

When

Conditional execution of stages based on branch, environment variables, expressions, etc.

stage('Deploy') {
  when { branch 'main' }
  steps { echo 'Deploying' }
}

Post Actions

Define actions that run after pipeline or stage completion, such as always , success , failure , and cleanup .

pipeline {
  agent any
  stages { ... }
  post {
    always { echo 'I will always say Hello again!' }
    failure { echo 'Build failed' }
  }
}

Kubernetes Integration

Jenkins can run pipelines inside Kubernetes pods using the kubernetes agent, specifying cloud, workspace volumes, and pod YAML.

pipeline {
  agent {
    kubernetes {
      cloud 'kubernetes'
      yaml '''
kind: Pod
metadata:
  name: jenkins-agent
spec:
  containers:
  - name: jnlp
    image: 'jnlp:alpine'
  - name: date
    image: 'alpine:latest'
    command: ["cat"]
''' 
    }
  }
  stages { ... }
}

Using Jenkinsfile in Source Control

Storing the Jenkinsfile in the project repository enables version control, code review, and collaboration.

Built‑in Environment Variables

Common variables include BUILD_NUMBER , BUILD_URL , JOB_NAME , WORKSPACE , etc.

pipeline {
  agent any
  stages {
    stage('Print Env') {
      steps { sh 'env' }
    }
  }
}

Dynamic Variables

Use returnStdout or returnStatus to capture command output or exit codes.

environment {
  CC = "${sh(returnStdout: true, script: 'echo -n clang')}"
  EXIT_STATUS = "${sh(returnStatus: true, script: 'exit 1')}"
}

Credential Management

Credentials can be injected as secret text, username/password pairs, or secret files, automatically creating additional environment variables.

pipeline {
  agent any
  environment {
    AWS_ACCESS_KEY_ID = credentials('txt1')
    AWS_SECRET_ACCESS_KEY = credentials('txt2')
  }
  stages { ... }
}