Skip to main content
In this lesson we compare the two primary styles for writing Jenkins pipelines: Declarative and Scripted. Both styles are saved in a Jenkinsfile, run by the same Jenkins Pipeline subsystem, use Apache Groovy, and can share logic through shared libraries. Choosing the right style depends on team skills, maintainability goals, and the complexity of pipeline logic.

​
Scripted Pipeline (Groovy-centric)

Scripted pipelines are written as full Groovy programs. They provide the maximum flexibility and control because you can use native Groovy constructs for complex logic, dynamic stage creation, loops, and advanced error handling. Key points:
  • Full access to Groovy language features.
  • Best for highly customized automation and advanced logic.
  • Requires Groovy knowledge and tends to have a steeper learning curve.
Example Scripted Jenkinsfile: 
node {
  stage('Checkout') {
    checkout scm
  }

  stage('Build') {
    sh 'mvn -B -DskipTests package'
  }

  stage('Test') {
    sh 'mvn test'
    junit 'target/surefire-reports/*.xml'
  }

  stage('Deploy') {
    if (env.BRANCH_NAME == 'main') {
      sh './deploy-prod.sh'
    } else {
      sh './deploy-staging.sh'
    }
  }
}
Trade-offs:
  • Pros: total control, dynamic behavior, complex branching logic.
  • Cons: harder to read for non-developers, more prone to inconsistent formatting and patterns across teams.

​
Declarative Pipeline (Structured and opinionated)

Declarative pipelines provide a structured, human-readable syntax with clearly defined top-level sections (for example: pipeline, agent, stages, steps, and post). This structure enforces best practices and consistency across teams. Key points:
  • Easier to learn and maintain—recommended as a default for most CI/CD workflows.
  • Built-in validation and more predictable behavior.
  • Intentionally limits arbitrary scripting to keep pipelines readable and standardized.
Example Declarative Jenkinsfile: 
pipeline {
  agent any

  stages {
    stage('Checkout') {
      steps {
        checkout scm
      }
    }

    stage('Build') {
      steps {
        sh 'mvn -B -DskipTests package'
      }
    }

    stage('Test') {
      steps {
        sh 'mvn test'
        junit 'target/surefire-reports/*.xml'
      }
    }
  }

  post {
    always {
      archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
    }
  }
}
When you need a bit of Groovy logic inside Declarative pipelines, use a script block for localized scripting: 
stage('Conditional') {
  steps {
    script {
      if (env.BRANCH_NAME == 'main') {
        sh './deploy-prod.sh'
      } else {
        sh './deploy-staging.sh'
      }
    }
  }
}
An infographic titled "Types of Pipeline Projects" comparing two pipeline styles: Scripted Pipeline and Declarative Pipeline. The left lists Scripted as code-centric, flexible, with a learning curve; the right lists Declarative as human-readable, easier to learn, and limited in complexity.
The diagram above summarizes the trade-offs: scripted pipelines prioritize flexibility and programmatic control, while declarative pipelines prioritize readability, consistency, and convention.

​
Quick comparison

FeatureScripted PipelineDeclarative Pipeline
Syntax styleFull Groovy scriptStructured DSL (pipeline { ... })
Ease of useLower (requires Groovy)Higher (clear layout)
FlexibilityVery highLimited by design, but extendable with script blocks
Best forComplex, dynamic workflowsStandard CI/CD flows, teams that value consistency
Error handling & controlProgrammatic via GroovyDeclarative post and built-in stages

​
Choosing between Declarative and Scripted

  • Use Declarative pipelines when you want:
    • A consistent, easy-to-read pipeline format.
    • Quick onboarding for new team members.
    • Predictable CI/CD flows that follow conventions.
  • Use Scripted pipelines when you need:
    • Fine-grained control, dynamic stage generation, or advanced Groovy logic.
    • Custom behaviors that are impractical to express in Declarative form.
  • Hybrid approach:
    • Start with Declarative for most work and use script blocks only where necessary.
    • Reserve pure Scripted pipelines for workflows that truly require full Groovy flexibility.
If you’re starting or want standardized, maintainable CI/CD, begin with Declarative pipelines. Move to Scripted pipelines only when your workflows require patterns or dynamic behavior that Declarative syntax cannot express.

Watch Video