When to use scripted over declarative in Jenkins - Deep Dive

Overview - When to use scripted over declarative

What is it?

Jenkins pipelines automate software build and delivery. There are two main ways to write these pipelines: scripted and declarative. Scripted pipelines use code-like syntax for full control, while declarative pipelines use a simpler, structured format. This topic explains when to choose scripted pipelines over declarative ones.

Why it matters

Choosing the right pipeline style affects how easy it is to write, read, and maintain automation. Without understanding when to use scripted pipelines, you might struggle with complex tasks or lose flexibility. This can slow down development and cause errors in your software delivery.

Where it fits

Before this, you should know basic Jenkins concepts and how pipelines work. After this, you can learn advanced pipeline features, pipeline libraries, and best practices for scaling Jenkins automation.

Mental Model

Core Idea

Scripted pipelines give you full programming control for complex automation, while declarative pipelines offer simplicity and structure for common tasks.

Think of it like...

Choosing between scripted and declarative pipelines is like deciding whether to cook from a recipe book (declarative) or freestyle cooking with your own ingredients and methods (scripted). The recipe book is easier and safer, but freestyle lets you create anything you imagine.

┌─────────────────────────────┐
│ Jenkins Pipeline Styles      │
├───────────────┬─────────────┤
│ Declarative   │ Scripted    │
├───────────────┼─────────────┤
│ Simple syntax │ Full control│
│ Structured    │ Flexible    │
│ Easy to read  │ Code-like   │
│ Less flexible │ Complex     │
└───────────────┴─────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding Jenkins Pipelines Basics

Concept: Learn what Jenkins pipelines are and their purpose in automation.

Jenkins pipelines automate steps like building, testing, and deploying software. They are scripts that tell Jenkins what to do. Pipelines help teams deliver software faster and with fewer mistakes.

Result

You know that pipelines are automation scripts in Jenkins for software delivery.

Understanding pipelines as automation scripts sets the stage for learning different ways to write them.

2

Foundation

Difference Between Scripted and Declarative

Concept: Recognize the two main pipeline styles and their basic differences.

Declarative pipelines use a simple, structured syntax with predefined blocks like 'stages' and 'steps'. Scripted pipelines use Groovy code, allowing loops, conditions, and custom logic. Declarative is easier for beginners; scripted is more flexible.

Result

You can identify declarative pipelines by their clear structure and scripted pipelines by their code-like style.

Knowing the styles helps you decide which fits your task complexity and team skills.

3

Intermediate

When Declarative Pipelines Fall Short

🤔Before reading on: do you think declarative pipelines can handle any complex logic easily? Commit to yes or no.

Concept: Understand the limits of declarative pipelines in handling complex automation needs.

Declarative pipelines are great for common workflows but struggle with complex loops, dynamic stages, or advanced error handling. They have strict syntax rules and limited programming features.

Result

You see that declarative pipelines may block you when your automation needs complex logic.

Recognizing declarative limits helps you know when to switch to scripted pipelines for flexibility.

4

Intermediate

Advantages of Scripted Pipelines

🤔Before reading on: do you think scripted pipelines require more coding skill than declarative? Commit to yes or no.

Concept: Learn why scripted pipelines offer more control and flexibility.

Scripted pipelines let you write Groovy code with loops, conditions, and variables. You can create dynamic stages and handle errors precisely. This control helps with complex workflows but needs programming knowledge.

Result

You understand scripted pipelines allow complex, customized automation beyond declarative limits.

Knowing scripted pipelines' power prepares you to use them when automation complexity grows.

5

Advanced

Mixing Declarative and Scripted Pipelines

🤔Before reading on: do you think you can use scripted code inside declarative pipelines? Commit to yes or no.

Concept: Explore how to combine both styles for best results.

Declarative pipelines support 'script' blocks where you can write scripted Groovy code. This lets you keep declarative structure but add complex logic when needed. It balances simplicity and power.

Result

You can write mostly declarative pipelines but insert scripted parts for complex tasks.

Understanding this hybrid approach helps you write maintainable pipelines with flexibility.

6

Expert

Choosing Scripted Pipelines in Production

🤔Before reading on: do you think scripted pipelines are always better for production? Commit to yes or no.

Concept: Learn when scripted pipelines are the best choice in real-world Jenkins setups.

In large projects with complex deployment logic, dynamic environments, or custom integrations, scripted pipelines shine. They allow fine-grained control and reuse of code. However, they require skilled developers and careful testing.

Result

You know scripted pipelines are ideal for complex, customized production workflows but need expertise.

Knowing when scripted pipelines are worth the complexity helps teams balance maintainability and power.

Under the Hood

Scripted pipelines run as Groovy code inside Jenkins, giving full access to programming constructs like loops, variables, and functions. Declarative pipelines are parsed into scripted pipelines by Jenkins, enforcing a structured syntax and predefined stages. Scripted pipelines execute step-by-step Groovy code, allowing dynamic decisions at runtime.

Why designed this way?

Jenkins introduced scripted pipelines first to give users full control. Declarative pipelines came later to simplify pipeline writing and reduce errors by enforcing structure. The design balances flexibility (scripted) and ease of use (declarative) to serve different user needs.

┌─────────────────────────────┐
│ Jenkins Pipeline Execution   │
├───────────────┬─────────────┤
│ Declarative   │ Scripted    │
├───────────────┼─────────────┤
│ Parsed to     │ Runs Groovy │
│ scripted code │ code directly│
│ Enforces      │ Full control│
│ structure     │ Dynamic logic│
└───────────────┴─────────────┘

Myth Busters - 3 Common Misconceptions

Quick: Do you think declarative pipelines can handle any complex logic just as well as scripted? Commit yes or no.

Common Belief: Declarative pipelines are powerful enough for all Jenkins automation needs.

Reality: Declarative pipelines have syntax and logic limits that make some complex workflows impossible or very hard to implement.

Why it matters: Believing this leads to frustration and wasted time trying to force declarative pipelines to do things better suited for scripted pipelines.

Quick: Do you think scripted pipelines are always harder to maintain than declarative? Commit yes or no.

Common Belief: Scripted pipelines are too complex and should be avoided for maintainability.

Reality: While scripted pipelines require coding skills, they can be well-structured and reusable, making them maintainable in skilled teams.

Why it matters: Avoiding scripted pipelines altogether can limit automation capabilities and force awkward workarounds.

Quick: Do you think you cannot mix scripted code inside declarative pipelines? Commit yes or no.

Common Belief: Declarative and scripted pipelines are completely separate and cannot be combined.

Reality: Declarative pipelines allow scripted Groovy code inside 'script' blocks for complex logic.

Why it matters: Not knowing this misses a powerful way to balance simplicity and flexibility.

Expert Zone

1

Scripted pipelines can leverage Groovy's full language features, but this also means you must manage code quality and complexity like in software development.

2

Declarative pipelines' strict syntax helps catch errors early, but sometimes subtle bugs appear only at runtime in scripted parts.

3

Using shared libraries with scripted pipelines enables code reuse and modular design, which is harder to achieve with pure declarative syntax.

When NOT to use

Avoid scripted pipelines if your automation is simple and your team lacks Groovy skills; use declarative pipelines instead for clarity and ease. For very complex workflows, consider external tools like Jenkins X or other CI/CD platforms that offer more advanced pipeline languages.

Production Patterns

Large organizations use scripted pipelines for multi-branch, multi-environment deployments with dynamic parameters. They combine scripted pipelines with shared libraries for reusable components and use declarative pipelines for simpler projects or teams with less coding experience.

Connections

Programming Languages

Scripted pipelines are like writing full programs, declarative pipelines are like configuration files.

Understanding programming vs configuration helps grasp why scripted pipelines offer more power but need more skill.

Infrastructure as Code (IaC)

Both Jenkins pipelines and IaC tools automate environments, but pipelines focus on process automation while IaC focuses on resource setup.

Knowing this distinction clarifies when to use pipelines for workflows and IaC for infrastructure.

Project Management

Choosing pipeline style relates to balancing complexity and maintainability, similar to choosing project methodologies (agile vs waterfall).

This connection helps understand trade-offs between flexibility and simplicity in team workflows.

Common Pitfalls

#1 Trying to write complex loops and dynamic stages in declarative pipelines without scripted blocks.

Wrong approach:

pipeline {
stages {
stage('Loop') {
steps {
for (int i=0; i<3; i++) {
echo "Iteration ${i}"
}
}
}
}
}

Correct approach:

pipeline {
agent any
stages {
stage('Loop') {
steps {
script {
for (int i=0; i<3; i++) {
echo "Iteration ${i}"
}
}
}
}
}
}

Root cause:

Declarative pipelines require scripted blocks for code logic; forgetting this causes syntax errors.

#2 Using scripted pipeline without proper error handling, causing pipeline failures.

Wrong approach:

node {
stage('Build') {
sh 'make build'
}
stage('Test') {
sh 'make test'
}
}

Correct approach:

node {
try {
stage('Build') {
sh 'make build'
}
stage('Test') {
sh 'make test'
}
} catch (err) {
echo "Build or test failed: ${err}"
currentBuild.result = 'FAILURE'
}
}

Root cause:

Scripted pipelines require explicit error handling; missing it leads to abrupt failures.

#3 Assuming declarative pipelines cannot include any scripted code.

Wrong approach:

pipeline {
agent any
stages {
stage('Example') {
steps {
echo 'Hello'
// No script block used for complex logic
}
}
}
}

Correct approach:

pipeline {
agent any
stages {
stage('Example') {
steps {
script {
echo 'Hello from scripted block'
// Complex logic here
}
}
}
}
}

Root cause:

Misunderstanding that declarative pipelines can embed scripted code blocks.

Key Takeaways

Jenkins pipelines automate software delivery using two styles: scripted for full control and declarative for simplicity.

Use scripted pipelines when your automation needs complex logic, dynamic stages, or advanced error handling.

Declarative pipelines are easier to write and maintain but have limits that scripted pipelines overcome.

You can combine both styles by embedding scripted code inside declarative pipelines for flexibility.

Choosing the right pipeline style balances team skills, project complexity, and maintainability.