Declarative vs Scripted Pipelines
Jenkins Pipeline as code comes in two syntactic flavors that compile down to the same underlying Groovy-based execution engine but present very different authoring experiences: declarative pipelines and scripted pipelines. Both are written in a Jenkinsfile and both support the same fundamental capabilities — stages, steps, agents, parallelism, post-build actions — but they differ sharply in structure, error checking, and how much of Groovy's full programming power is exposed to the pipeline author. Choosing between them is a real engineering decision with consequences for maintainability, onboarding, and how easily a pipeline can be linted or validated before it runs.
Cricket analogy: Test cricket and T20 cricket are both played under the same laws of the game and by the same governing body, but they present wildly different experiences to players and fans, and a team's choice between formats to prioritize is a real strategic decision.
Declarative pipeline: structure and validation
A declarative pipeline begins with the pipeline { } block and enforces a fixed, predictable structure: a top-level agent, an ordered list of stages, each containing steps, plus optional environment, options, parameters, triggers, and post sections. This structure is intentionally restrictive — it reads almost like a configuration file rather than a program — and that restriction is the point: the Jenkins Declarative Pipeline plugin can statically validate a Jenkinsfile's syntax before running a single step, catching typos and structural errors immediately rather than failing mid-build. This predictability also makes declarative syntax far friendlier to Jenkins' Blue Ocean visualization and to engineers who are not fluent in Groovy.
Cricket analogy: A T20 franchise's fixed batting order, submitted to the umpires before the toss, is rigid by design — the structure itself lets the scorer catch an invalid entry immediately rather than discovering a problem mid-innings, and it's far easier for a new player to follow.
Scripted pipeline: full Groovy programmability
A scripted pipeline begins with a plain node { } block and is, underneath, an arbitrary Groovy script executed step-by-step by the Groovy CPS (Continuation-Passing Style) interpreter. There is no fixed structure to conform to: you can use if/else, for and while loops, try/catch, custom functions, and arbitrary variable manipulation directly, because the entire thing is just imperative code calling Jenkins step functions like sh, git, and stage. This gives scripted pipelines strictly more expressive power for genuinely complex, highly conditional pipeline logic, at the cost of losing declarative's upfront structural validation and being noticeably harder for newcomers to read and safely modify.
Cricket analogy: A street cricket match with no fixed overs or formal rules — just an open-ended game that keeps going, adapts its own boundaries, and lets players improvise custom rules on the fly — gives far more flexibility than a formal T20 but is much harder for an outsider to follow.
// Declarative pipeline
pipeline {
agent any
options { timestamps() }
stages {
stage('Build') {
steps { sh 'mvn clean package' }
}
stage('Test') {
steps { sh 'mvn test' }
}
}
post {
failure { mail to: '[email protected]', subject: 'Build failed', body: 'Check console output.' }
}
}
// Equivalent scripted pipeline
node {
try {
stage('Build') {
sh 'mvn clean package'
}
stage('Test') {
sh 'mvn test'
}
} catch (err) {
mail to: '[email protected]', subject: 'Build failed', body: 'Check console output.'
throw err
}
}A declarative pipeline can still escape into arbitrary Groovy when needed, via the script { } block allowed inside any steps section — this is a deliberate escape hatch, letting teams get declarative's structure and validation for 95% of a pipeline while dropping into imperative code for the rare stage that genuinely needs a loop or complex conditional.
Both pipeline types run under the Groovy CPS interpreter's sandbox, which transforms code so it can be paused and resumed (important for surviving controller restarts mid-build) — but this transformation has known quirks, such as certain Groovy idioms (some closures, non-serializable objects held across a step boundary) triggering confusing NotSerializableException errors. This is more often encountered in scripted pipelines because of their higher code complexity, but it is a CPS-engine issue, not exclusive to either syntax.
For the large majority of CI/CD pipelines — checkout, build, test, package, deploy in a mostly linear or matrix-parallel shape — declarative is the recommended default: it is easier to review, easier to lint (Jenkinsfile syntax can be validated via the 'Replay' feature or the jenkins-cli declarative-linter), and easier for a team to standardize on. Scripted pipelines remain valuable for genuinely irregular logic — dynamically generating a variable number of parallel stages from a runtime-computed list, or implementing custom retry/backoff logic that declarative's built-in retry() option cannot express — and mature Jenkinsfiles often combine both: a declarative skeleton with script { } blocks for the handful of steps that need it.
Cricket analogy: For most club-level matches, a standard fixed batting order is the sensible default because it's easy for the scorer and captain to review, but a genuinely unusual situation like a rain-shortened chase still calls for the captain's ad-hoc reshuffling of the order mid-innings.
- Declarative pipelines use a fixed
pipeline { agent, stages, post }structure that Jenkins can validate before execution starts. - Scripted pipelines use a plain
node { }block and full imperative Groovy, offering maximum flexibility with less upfront validation. - Both compile to the same underlying Groovy CPS interpreter, which is why both can hit CPS-serialization quirks.
- Declarative's
script { }block is an escape hatch into arbitrary Groovy inside an otherwise-structured pipeline. - Declarative is the recommended default for most linear/matrix CI pipelines due to readability and validation.
- Scripted suits highly dynamic or conditional pipeline logic that declarative's directives cannot cleanly express.
Practice what you learned
1. What top-level block does a declarative Jenkinsfile begin with?
2. What key advantage does declarative syntax have over scripted syntax before a build even starts?
3. How can a declarative pipeline execute arbitrary imperative Groovy code for a case its directives can't express?
4. What underlying execution engine do both declarative and scripted pipelines share?
5. Which scenario most strongly favors a scripted pipeline over declarative?
Was this page helpful?
You May Also Like
Jenkinsfile Fundamentals
Learn the core building blocks of a Jenkinsfile — agent, stages, steps, environment, parameters, and post — and how Pipeline as Code changed Jenkins pipeline management.
Jenkins Architecture Basics
Understand Jenkins' controller/agent architecture, how builds are distributed to executors, and the core components — controller, agents, executors, and the job queue.
Jenkins Plugins and Agents
Explore how Jenkins' plugin ecosystem extends core functionality and how agents are provisioned, connected, and secured — including static, SSH, and dynamic cloud agents.
Designing Multi-Stage Pipelines
Learn how to structure a CI/CD pipeline into logical stages — build, test, package, deploy — so failures surface early and each stage has a clear contract with the next.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics