When to use scripted over declarative in Jenkins - Commands & Configuration

Introduction

Sometimes you need more control and flexibility in your Jenkins pipelines than the simple, easy-to-read style offers. Scripted pipelines let you write code that can do complex tasks and decisions step-by-step, solving problems that the simpler style can't handle well.

When your build process needs complex loops or conditional logic that declarative syntax cannot express easily.

When you want to write custom Groovy code to interact with Jenkins internals or plugins.

When you need to dynamically create or modify pipeline steps based on runtime information.

When you want full control over the flow of your pipeline without the restrictions of declarative rules.

When migrating older Jenkins pipelines that were originally written in scripted style.

Commands

Check that Jenkins Job Builder is installed and ready to use for managing Jenkins jobs.

Terminal

jenkins-jobs --version

Expected Output

3.10.0

Create a simple scripted pipeline Jenkinsfile that runs a build stage with a message.

Terminal

echo 'node { stage("Build") { echo "Building..." } }' > Jenkinsfile

Expected Output

No output (command runs silently)

Trigger the Jenkins pipeline job named 'my-pipeline' that uses the scripted Jenkinsfile.

Terminal

jenkins-cli build my-pipeline

Expected Output

[Pipeline] node

[Pipeline] stage

[Pipeline] { (Build)

[Pipeline] echo

Building...

[Pipeline] }

[Pipeline] // stage

[Pipeline] End of Pipeline

Finished: SUCCESS

View the console output of the last run of the 'my-pipeline' job to verify the scripted pipeline ran correctly.

Terminal

jenkins-cli console my-pipeline

Expected Output

Building...

Finished: SUCCESS

Key Concept

If you remember nothing else from this pattern, remember: scripted pipelines give you full coding power for complex workflows, while declarative pipelines keep things simple and structured.

Common Mistakes

Trying to use declarative-only syntax features inside a scripted pipeline.

Scripted pipelines do not support declarative syntax rules, causing errors or unexpected behavior.

Use pure Groovy code and Jenkins pipeline steps in scripted pipelines, or switch to declarative syntax if you want those features.

Writing overly complex scripted pipelines without comments or structure.

Makes the pipeline hard to read, maintain, and debug.

Keep scripted pipelines organized with clear stages and comments, or use declarative pipelines when possible.

Summary

Scripted pipelines allow writing complex, flexible Jenkins workflows using Groovy code.

Use scripted pipelines when you need advanced logic or dynamic behavior not possible in declarative pipelines.

Declarative pipelines are simpler and easier to read but less flexible than scripted pipelines.