Jenkinsfile Validation Using the Jenkinsfile Maven Plugin
Posted: December 28th, 2016 | Author: sabre1041 | Filed under: Technology | No Comments »
The release of Jenkins 2.0 officially adopted first class support for the concept of pipelines as code as a way to describe the steps an application will take as part of a continuous integration and continuous deployment process. While the entire pipelines as code concept slowly evolved out of the existing Jenkins ecosystem, it ushered in a new method for how developers interact with both the Jenkins server as well as the organization of their source code. Instead of multiple Jenkins jobs chained together to form a “pipeline”, the Jenkinsfile was introduced where each step in the process could be defined in a single unit that could be included inline as part of the Pipeline job in the Jenkins server, or within the source code of a project. It is recommended to store a Jenkinsfile with source code in a source code management system (SCM), such as git, in order to achieve full traceability and history of the pipeline
Even though pipelines provides a powerful and extensive framework, one of the challenges faced by those developing Jenkinsfiles are the specific syntaxes that can be applied. This can be partially attributed to a prior familiarity with a GUI based configuration approach, or lack of extensive formal documentation and tooling. To address these shortcomings, a new plugin called the Pipeline-Model-Definition plugin was developed which focused on a declarative methodology for describing Jenkinsfiles. The result is a syntax that is both easier to develop and understand as it models the pattern of the traditional freestyle job type.
pipeline {
agent docker:'maven:3.3.3'
stages {
stage('build') {
steps {
sh 'mvn --version'
sh 'mvn install'
}
}
}
}
A more in depth look at the pipeline-model-definition plugin and declarative syntax can be found in the article, Announcing the beta of Declarative Pipeline Syntax.
One of the features also included in the Pipeline-Model-Definition plugin is the ability to validate the contents and syntax of a Jenkinsfile. Validation is performed by an exposing functionality to remotely verify the provided Jenkinsfile’s conforms with the configuration of the target Jenkins server. This was a much-needed enhancement that had been missing in the entire pipelines ecosystem. Since the content of a Jenkinsfile is groovy based, a developer could perform some form of initial validation on their local machine. The true test to whether a Jenkinsfile was syntactically correct could only occur once it was executed on the Jenkins server resulting in additional testing and development cycles if any issues arose.
Before a Jenkinsfile can be validated, the Pipeline-Model-Definition plugin must be installed on the Jenkins server. Login to the Jenkins server and select Manage Jenkins. Select Manage Plugins and on the Available tab to view the available plugins. Locate the Pipeline: Model Definition plugin and select Download now and install after restart.
With the plugin installed, a developer could make use of one of two methods to verify their Jenkinsfile from their machine:
SSH:
curl -X POST ` -F "jenkinsfile=<Jenkinsfile" JENKINS_URL/pipeline-model-converter/validate
HTTP:
curl -X POST ` -F "jenkinsfile=<Jenkinsfile" JENKINS_URL/pipeline-model-converter/validate
An additional step to the invocation would need to occur if Cross Site Request Forgery (CSRF) protection was enabled resulting in the following command:
curl -X POST -H `curl 'JENKINS_URL/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)'` -F "jenkinsfile=<Jenkinsfile" JENKINS_URL/pipeline-model-converter/validate
Each of the prior commands assumes a file called Jenkinsfile is present in the current directory.
While these options for validating a Jenkinsfile are certainly useful, they do fall outside of the actions a typical developer would take to build and test their application code. Instead, another approach would be to directly integrate the validation into an existing build process. For Java based applications, a Maven plugin called the jenkinsfile-maven-plugin has been developed to streamline the validation process.
The jenkinsfile-maven-plugin can be added to a project’s pom.xml file by including the following content:
<plugin>
<groupId>com.andyserver.maven.plugins</groupId>
<artifactId>jenkinsfile-maven-plugin</artifactId>
<version>${jenkinsfile.maven.plugin.version}</version>
</plugin>
Since the validation process occurs on the Jenkins server, the plugin must be configured with the location of the server and any applicable authentication details as shown below:
<plugin>
<groupId>com.andyserver.maven.plugins</groupId>
<artifactId>jenkinsfile-maven-plugin</artifactId>
<version>${jenkinsfile.maven.plugin.version} </version>
<configuration>
<server>https://jenkins.example.com:8080/jenkins</server>
<username>admin</username>
<password>password</password>
</configuration>
</plugin>
Once the plugin has been properly configured, the validation of the Jenkinsfile within a project can be executed by running the following command:
mvn jenkinsfile:validate
Any errors in the validation process will cause the build to fail and the specific exception to be printed out.
A full list of available options can be found within the project repository.
Being able to validate the content of a Jenkinsfile during the development process helps ensure compliance with both the structure of the Jenkinsfile and the available tools on the Jenkins server. Each of these benefits helps shorten the overall software development lifecycle and release software faster.
Recent Comments