Announcing the beta of Declarative Pipeline Syntax

Published on 12/19/2016 by Patrick Wolf

Last week we released version 0.7.1 of the Pipeline-Model-Defintion plugin and wanted to crown it as the official Beta version of the Declarative Pipeline syntax. Although it has been available in the update center since August, we continue to solidify the syntax. We feel this release is getting very close to the final version and should not change much before 1.0. However, it is still a Beta so further tweaks are possible.

A release (0.8.0) is planned for early January 2017 which will finalize the syntax with the following changes: JENKINS-40524, JENKINS-40370, JENKINS-40462, JENKINS-40337

What is Declarative Pipeline?

All the way back at Jenkins World in September, Andrew Bayer presented a sneak peak of a new syntax for constructing Pipelines. We are calling this new syntax Declarative Pipeline to differentiate it from the existing Scripted Pipeline syntax that has always been a part of Pipeline.

After listening to many Jenkins users over the last year we felt that, while Pipeline Script provides tremendous power, flexibility, and extensibility, the learning curve for Scripted Pipeline was steep for users new to either Jenkins or Pipeline. Beginning users wanting to take advantage of all the features provided by Pipeline and Jenkinsfiles were required to learn Scripted Pipeline or remain limited to the functionality provided by Freestyle jobs.

Declarative Pipeline does not replace Scripted Pipeline but extends Pipeline it with a pre-defined structure to let users focus entirely on the steps required at each stage without needing to worry about scripting every aspect of the pipeline. Granular flow-control is extremely powerful and Scripted Pipeline syntax will always be part of Pipeline but it’s not for everyone.

Declarative Pipeline enables all users to connect simple, declarative blocks that define agents (including Docker), post actions, environment settings, credentials and all stages that make up the pipeline. Best of all, because this Declarative syntax is part of Pipeline, all build steps and build wrappers available in Plugins or loaded from Shared Libraries are also available as steps in Declarative.

Example

Below is an example of a pipeline in Declarative syntax. You can also switch the view to show the same pipeline in Scripted syntax. The Declarative syntax has a more straightforward structure that is easier to grok by users not versed in Groovy.

// Declarative //
pipeline {
  agent  label:'has-docker', dockerfile: true
  environment {
    GIT_COMMITTER_NAME = "jenkins"
    GIT_COMMITTER_EMAIL = "jenkins@jenkins.io"
  }
  stages {
    stage("Build") {
      steps {
        sh 'mvn clean install -Dmaven.test.failure.ignore=true'
      }
    }
    stage("Archive"){
      steps {
        archive "*/target/**/*"
        junit '*/target/surefire-reports/*.xml'
      }
    }
  }
  post {
    always {
      deleteDir()
    }
    success {
      mail to:"me@example.com", subject:"SUCCESS: ${currentBuild.fullDisplayName}", body: "Yay, we passed."
    }
    failure {
      mail to:"me@example.com", subject:"FAILURE: ${currentBuild.fullDisplayName}", body: "Boo, we failed."
    }
  }
}

// Script //
withEnv(["GIT_COMMITTER_NAME = jenkins","GIT_COMMITTER_EMAIL = jenkins@jenkins.io"]) {
  node('has-docker') {
    try {
      checkout scm // checks out Dockerfile and source code
      def myImage = docker.build 'my-environment:snapshot'
      myImage.inside {
        stage('Build') {
          sh 'mvn clean install -Dmaven.test.failure.ignore=true'
        }
        stage('Archive') {
          archive "*/target/**/*"
          junit '*/target/surefire-reports/*.xml'
        }
      }
      if (currentBuild.result == null || currentBuild.result == 'SUCCESS') {
        mail to:"me@example.com", subject:"SUCCESS: ${currentBuild.fullDisplayName}", body: "Yay, we passed."
      }
    }
    catch (exc) {
      mail to:"me@example.com", subject:"FAILURE: ${currentBuild.fullDisplayName}", body: "Boo, we failed."
    }
    finally {
      deleteDir()
    }
  }
}

How can you help?

Install the lastest version of the Pipeline-Model-Defintion plugin.
Read the documentation: Getting Started and Syntax overview. (These documents will be incorporated into the Jenkins.io documentation.)
Convert some of your existing Pipeline scripts into Declarative
Log any issues or enhancements you have here for the syntax, the execution, or the documentation.
Ask questions. You can send questions to the users mailing list or visit the #jenkins channel on IRC.

How will this work with Blue Ocean?

Blue Ocean is all about Pipelines in Jenkins. Running, displaying, and soon, creating Pipelines. Blue Ocean will be able to run and display Pipelines written in this new syntax just like any other Pipeline works today. However, because Declarative Pipeline includes a pre-defined structure, or model, it is now possible to create and edit pipelines with a GUI editor.

Pipeline Editor

Although we plan to launch 1.0 of Declarative Pipeline before Blue Ocean 1.0 is officially available, we expect to have a working Beta of the Editor available to play with. The combination of a simple syntax and an intuitive editor should make creating Jenkins Pipelines a breeze.

Happy Holidays

I hope everyone has a great end of the year and a Happy New Year. With Declarative Pipeline and Blue Ocean we expect great things for Jenkins in 2017!

About the Author