Choosing Between Declarative and Scripted Pipeline Syntax in Jenkins

Problem and Takeaway

Jenkins pipelines can be written in two syntaxes that compile to the same CPS‑transformed bytecode. Declarative Pipeline gives you a guarded, opinionated structure with built‑in linting, stage restart, and post‑condition blocks. Scripted Pipeline offers full Groovy control flow for dynamic stage generation and advanced metaprogramming. The decision hinges on how much structure you want versus how much flexibility you need.

Decision Constraints

• Team familiarity – Declarative is easier for newcomers; Scripted assumes comfort with Groovy.
• Pipeline complexity – Static stage lists fit Declarative; matrix or data‑driven stage sets need Scripted.
• Tooling requirements – Blue Ocean editor, Pipeline Linter, and when/environment/options directives work only with Declarative.
• Existing codebase – Legacy Groovy job DSLs migrate incrementally by wrapping Scripted blocks in script steps.

Feature Comparison

Trade‑offs

When Declarative Wins

• Standard CI/CD pipelines with a known set of stages (build, test, deploy).
• Teams that benefit from visual editing in Blue Ocean and want restartable stages.
• Projects that need declarative when conditions, environment variables, or options like timeout without boilerplate.

When Scripted Wins

• Pipelines that compute their stage list at runtime (e.g., matrix builds from a JSON file).
• Heavy use of Groovy metaprogramming, custom DSLs, or shared library internals.
• Migration of existing Groovy‑based job DSLs where a full rewrite is impractical.

Concrete Implementation Examples

Declarative Jenkinsfile

pipeline {
  agent any
  options {
    timeout(time: 30, unit: 'MINUTES')
    timestamps()
  }
  environment {
    DOCKER_REGISTRY = 'registry.example.com'
  }
  stages {
    stage('Build') {
      steps {
        sh 'make build'
      }
    }
    stage('Test') {
      when { branch 'main' }
      steps {
        sh 'make test'
      }
      post {
        always { junit 'reports/*.xml' }
        failure { mail to: '[contact removed]', subject: "Test failed: ${env.JOB_NAME}", body: 'See console.' }
      }
    }
    stage('Deploy') {
      when { branch 'main' }
      steps {
        script {
          // optional dynamic logic inside a script block
          def tag = "${env.BUILD_NUMBER}"
          sh "docker push ${env.DOCKER_REGISTRY}/myapp:${tag}"
        }
      }
    }
  }
  post {
    always { cleanWs() }
    success { echo 'Pipeline succeeded.' }
    failure { echo 'Pipeline failed.' }
  }
}

Scripted Jenkinsfile

node('linux') {
  stage('Checkout') {
    checkout scm
  }
  def stages = ['unit', 'integration', 'contract']
  for (def testType : stages) {
    stage("Test ${testType}") {
      try {
        sh "make test-${testType}"
      } catch (err) {
        currentBuild.result = 'UNSTABLE'
        echo "${testType} tests failed: ${err}"
      }
    }
  }
  stage('Package') {
    docker.image('myorg/builder:latest').inside {
      sh 'make package'
    }
  }
  stage('Deploy') {
    if (env.BRANCH_NAME == 'main') {
      sh "docker push registry.example.com/myapp:${env.BUILD_NUMBER}"
    }
  }
}

Validation Steps

1. Lint Declarative syntax – On a machine with Jenkins CLI installed (requires Overall/Read permission):
   

   java -jar jenkins-cli.jar -s https://jenkins.example.com/ declarative-linter < Jenkinsfile

   Expected output: Jenkinsfile successfully validated. Any error prints line/column details. Risk: CLI must authenticate (use -auth or API token).
2. Run a minimal Scripted pipeline – Create a test job (Freestyle → Pipeline script) and paste the Scripted example. Trigger a build; verify the console shows each stage executing. No special permissions beyond Job/Build.
3. Confirm stage restart – In Blue Ocean, open a completed Declarative run, click a failed stage, choose Restart from stage. The pipeline should resume at that stage without re‑running prior stages. This only works if the pipeline contains no script blocks with non‑CPS side effects.
4. Check CPS transformation parity – Tail the Jenkins system log (/var/log/jenkins/jenkins.log or /log/all in the UI) for lines containing org.jenkinsci.plugins.workflow.cps.CpsFlowExecution. Both syntaxes should produce similar entries, confirming they share the same execution engine.

Limitations and Practical Checks

• Declarative forbids top‑level Groovy variables or functions; any such code must live inside a script block.
• Stage restart is unsafe if a script block mutates global state (e.g., writes to a file on the controller).
• Nested node blocks in Scripted can deadlock on small executor pools; prefer a single outer node and use docker.image(...).inside() for container steps.
• Shared library global variables (vars/foo.groovy) are always written in Scripted style, even when called from Declarative.

To verify your choice works in production, promote the validated Jenkinsfile to a real multibranch pipeline job, run a few builds, and confirm that Blue Ocean shows restart icons for Declarative runs and that Scripted runs execute the dynamic stage loop without executor starvation.