Chapter 21: Jenkins Pipeline and Jenkinsfile

21.2 Declarative vs Scripted (pick Declarative)

By Ravindra Bagale · Last updated: 25 October 2026

Why: the problem

Jenkins gives you two ways to write a pipeline. Declarative and Scripted. Both run on the same engine. Think of a recipe at a restaurant like Haldiram's. Declarative is a printed form. It has fixed boxes: ingredients, steps, serving. Anyone in the kitchen can read it. Scripted is a free notebook. You can write anything, but a new cook may not understand it. In most companies, like Infosys or TCS project teams, the rule is simple. Use Declarative for normal builds. Use a small script block only when you really need a loop or a complex choice. Declarative also checks the file before running. A typo in a block name fails in one second, not after ten minutes of build. In this lesson you will write the same build both ways, run both, and see why teams pick Declarative.

What we will build

You will write one build in Declarative style and one in Scripted style. You will break each on purpose and compare the errors. Then you will add a small script block inside Declarative for a loop.

What: every term in plain English

• Declarative pipeline — Starts with pipeline {. Has fixed blocks like agent, stages, post. Easy to read and checked early.
• Scripted pipeline — Starts with node {. Plain Groovy code. Very flexible, harder to read.
• node — In Scripted, asks for an executor and a workspace.
• script block — A small piece of Scripted code allowed inside a Declarative step.
• Validation — Declarative checks the shape of the file before any stage runs.
• Sandbox — A safety layer that blocks dangerous Groovy methods.
• DSL — Domain specific language. The set of words Jenkins adds, like sh and stage.

How: step by step

1. Write the Declarative file

   nano Jenkinsfile
   

   What it does: Uses pipeline, agent, stages, steps.

   Output

   (file saved)
   

2. Write the Scripted file

   nano Jenkinsfile.scripted
   

   What it does: Uses node and stage with plain Groovy.

   Output

   (file saved)
   

3. Make two jobs

   New Item > badge-decl (Script Path Jenkinsfile)
   New Item > badge-scr (Script Path Jenkinsfile.scripted)
   

   What it does: Two Pipeline jobs, one per style.

   Output

   Saved
   

4. Run both

   Build Now on each job
   

   What it does: Both show the same stages and output.

   Output

   Finished: SUCCESS
   

5. Break Declarative

   Change steps to step in one stage and push
   

   What it does: Declarative fails before running.

   Output

   WorkflowScript: 5: Unknown stage section "step"
   

6. Break Scripted

   Misspell sh as shh and push
   

   What it does: Scripted fails only when it reaches that line.

   Output

   No such DSL method shh found
   

Example 1: Declarative style

Stack. Jenkins Declarative

Goal. Declarative style.

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Build') {
      steps {
        sh 'npm ci'
        sh 'npm run build'
      }
    }
    stage('Test') {
      steps { sh 'npm test' }
    }
  }
  post {
    always { echo "Result: ${currentBuild.currentResult}" }
  }
}

What each line does

• pipeline — Root block. Must be the first word.
• agent any — Where to run.
• stages / stage / steps — The fixed three levels. Steps hold the real work.
• post always — Runs at the end, pass or fail.
• currentBuild.currentResult — SUCCESS, UNSTABLE or FAILURE so far.

Green output

[Pipeline] stage (Build)
+ npm ci
+ npm run build
[Pipeline] stage (Test)
+ npm test
Tests: 9 passed, 9 total
Result: SUCCESS
Finished: SUCCESS

Expected result. A clean, fixed shape. A new team member can read it in a minute.

Example 2: Scripted style for the same build

Stack. Jenkins Scripted

Goal. Scripted style for the same build.

Jenkinsfile.scripted

node {
  try {
    stage('Checkout') { checkout scm }
    stage('Build') {
      sh 'npm ci'
      sh 'npm run build'
    }
    stage('Test') { sh 'npm test' }
  } catch (err) {
    currentBuild.result = 'FAILURE'
    throw err
  } finally {
    echo "Result: ${currentBuild.currentResult}"
  }
}

What each line does

• node { — Takes an executor and a workspace.
• stage('Checkout') { checkout scm } — Scripted does not clone by itself, you must ask.
• try / catch / finally — Plain Groovy error handling. This replaces post.
• throw err — Fails the build after marking it.

Green output

[Pipeline] node
Running on Jenkins in /var/jenkins_home/workspace/badge-scr
[Pipeline] stage (Checkout)
[Pipeline] stage (Build)
+ npm ci
[Pipeline] stage (Test)
Tests: 9 passed, 9 total
Result: SUCCESS
Finished: SUCCESS

Expected result. Same result, but you wrote the error handling yourself. More code, more chances for mistakes.

Example 3: Declarative with a small script block for a loop

Stack. Jenkins Declarative with script

Goal. Declarative with a small script block for a loop.

Jenkinsfile

pipeline {
  agent any
  stages {
    stage('Smoke pages') {
      steps {
        script {
          def pages = ['index.html', 'about.html', 'contact.html']
          for (p in pages) {
            sh "test -f dist/${p} && echo OK ${p}"
          }
        }
      }
    }
  }
}

What each line does

• script { — Opens a small Scripted area inside a Declarative step.
• def pages = [...] — A Groovy list.
• for (p in pages) — Loops over the list.
• sh "...${p}" — Double quotes let Groovy put the value of p into the command.

Green output

[Pipeline] script
+ test -f dist/index.html
OK index.html
+ test -f dist/about.html
OK about.html
+ test -f dist/contact.html
OK contact.html
Finished: SUCCESS

Expected result. You kept the readable Declarative shape and used code only where you needed it.

Example 4: Convert a real Scripted job to Declarative

Stack. Jenkins

Goal. Convert a real Scripted job to Declarative.

old Jenkinsfile (Scripted)

node('linux') {
  stage('Build') {
    timeout(time: 10, unit: 'MINUTES') {
      sh 'npm ci && npm run build'
    }
  }
  stage('Archive') { archiveArtifacts 'dist/**' }
}

new Jenkinsfile (Declarative)

pipeline {
  agent { label 'linux' }
  options { timeout(time: 10, unit: 'MINUTES') }
  stages {
    stage('Build') { steps { sh 'npm ci && npm run build' } }
  }
  post { success { archiveArtifacts 'dist/**' } }
}

What each line does

• node('linux') — Becomes agent label linux.
• timeout around a step — Becomes options timeout for the whole pipeline.
• Archive stage — Becomes post success, so it runs only on green.
• Result — Same build, fewer lines, checked before it runs.

Green output

[Pipeline] stage (Build)
+ npm ci && npm run build
build done: dist/index.html
Archiving artifacts
Finished: SUCCESS

Expected result. You will do this kind of move often at work. Run both versions once and compare the logs.

Verify: did it work?

1. Check the shape online

   Job > Pipeline Syntax > Declarative Directive Generator
   

   What it does: Builds correct blocks for you to copy.

   Output

   Generated: options { timeout(time: 10, unit: MINUTES) }
   

2. Validate from the terminal

   curl -s -X POST -u admin:API_TOKEN -F "jenkinsfile=@Jenkinsfile" http://localhost:8080/pipeline-model-converter/validate
   

   What it does: Checks a Declarative file without running it.

   Output

   Jenkinsfile successfully validated.
   

When it is red 1

WorkflowScript: 5: Unknown stage section "step". Starting with version 0.5, steps in a stage must be in a steps block.

Cause. You wrote step instead of steps, or put sh straight inside stage.

Fix, step by step

1. Wrap the commands in steps { }.
2. Validate with the linter.

When it is red 2

No such DSL method 'shh' found among steps

Cause. A typo in a step name in Scripted code.

Fix, step by step

1. Fix the spelling.
2. Use the Snippet Generator to copy step names.

When it is red 3

Scripts not permitted to use method java.io.File

Cause. The sandbox blocked a Groovy method.

Fix, step by step

1. Use a Jenkins step like readFile instead.
2. Ask an admin before approving in In-process Script Approval.

Cleanup

1. Delete the test jobs

   badge-decl > Delete Pipeline, badge-scr > Delete Pipeline
   

   What it does: Removes the practice jobs.

   Output

   Deleted
   

2. Remove the scripted file

   git rm Jenkinsfile.scripted && git commit -m "remove scripted demo" && git push
   

   What it does: Keeps only one Jenkinsfile in the repo.

   Output

   1 file changed, 15 deletions(-)
   

Practice tasks

Homework: try at home

Recap

• Declarative has a fixed shape and early checks.
• Scripted is plain Groovy, flexible but harder.
• Use Declarative by default.
• Use script blocks only for loops or complex logic.
• Validate files before push.

FAQ

Can I mix both styles?

Yes, by using script blocks inside Declarative steps.

Is Scripted faster?

No. Both run on the same engine.

Which style do interviews expect?

Declarative, with knowledge of what a script block is.

Why does the sandbox block some code?

To stop pipelines from reading files or running code on the controller.

Where do I find all step names?

Pipeline Syntax > Snippet Generator.

Interview questions

1. Declarative vs Scripted?

   Declarative has a fixed, validated structure and is easy to read. Scripted is plain Groovy inside node blocks and is flexible. Use Declarative and add script blocks when needed.

2. What is a script block?

   A block inside Declarative steps where you can write Scripted Groovy like loops.

3. How do you handle errors in Scripted?

   With try, catch and finally, and by setting currentBuild.result.

4. How do you validate a Jenkinsfile?

   With the pipeline-model-converter validate endpoint or the VS Code Jenkins linter.

5. What is the Groovy sandbox?

   A security layer that only allows approved methods in pipeline code.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview cardComparison card

मराठी cards