Jenkins Shared Library Tutorial For Beginners

In this tutorial, we’ll cover the essential concepts of Jenkins shared libraries and provide a hands-on guide to creating shared libraries for pipelines.

We are in an era of microservices where modern applications are split into individually deployable components. As compared to a monolithic application, you might have many pipelines to deploy individual microservices.

With Jenkins pipeline as code, we can code our entire CI/CD process. It is treated the same way we develop applications. You can version your pipeline code and perform all levels of testing before using it for any application deployments.

What is Jenkins Shared Library?

When we say CI/CD as code, it should have modularity and reusability. And mainly it should follow the DRY principles. This is where Jenkins Shared Library comes into play.

Shared library – A library that can be shared.

Jenkins Shared library is the concept of having a common pipeline code in the version control system that can be used by any number of pipelines just by referencing it. In fact, multiple teams can use the same library for their pipelines.

You can compare it with the common programming library. In programming, we create individual libraries that can be used by anyone just by importing them into their code.

Assume, you have ten Java microservices pipelines, the maven build step gets duplicated on all the ten pipelines. And whenever a new service gets added, you will have to copy and paste the pipeline code again. Now, let’s say you want to change some parameters in the Maven build step. You will have to change it in all the pipelines manually.

To avoid pipeline code duplication, we can write a shared library for Maven build, and in all the pipelines we just have to refer to the Maven build library code. In the future for any Maven build changes, all you have to update the shared library code. It will be applied to all the pipelines using the Maven build library.

Shared Library Github Repo

The Jenkins shared library examples used in this guide are hosted on a GitHub Repository.

Clone the repository to follow along with the guide.

git clone https://github.com/techiescamp/jenkins-shared-library

Getting Started With Shared Library

A shared library is a collection of Groovy files (DSLs + Groovy). All the Groovy files should be present in a git repo.

In this example, we will be using Github as our Git repo. 

You can clone this repo to get the basic structure of the shared library.

The shared library repo has the following folder structure.

jenkins-shared-library
|____resources
|____src
|____vars

Let’s understand what each folder means.

vars

This directory holds all the global shared library code that can be called from a Jenkins pipeline. It holds all the library files with a .groovy extension.

Here is a simple library code for Git checkout.

def call(Map stageParams) {

    checkout([
        $class: 'GitSCM',
        branches: [[name:  stageParams.branch ]],
        userRemoteConfigs: [[ url: stageParams.url ]]
    ])
  }

Don’t worry about the syntax. We can generate it using the Jenkins pipeline generator. We will look at it practically in the following sections.

The vars directory also supports .txt files for the documentation of shared library code.

For example, if you have a file named maven-build.groovy, you can have a helper file named maven-groovy.txt. In this file, you can write the respective shared library function help documentation in markdown format.  The help file can be viewed from <your-jenkins-url>/pipeline-syntax/globals page. 

src

It is a regular Java source directory. Here you can add custom structured and object-oriented code Groovy code to extend your shared library code. Also, you can import core Jenkins and its plugin classes using an import statement.

You might ask, when we have a vars directory, what is the need for src?

There are scenarios where the groovy DSLs will not be flexible enough to achieve some complex functionalities. In this case, you can write custom Groovy functions in src and call them in your shared library code.

The src directory is added to the classpath during every script compilation. So we can directly use the classes defined in the src directory in Jenkinsfiles.

resources

All the non-groovy files required for your ur pipelines can be managed in this folder. Typically files.

One such example is, you might need a common JSON template to make an API call during the build. This JSON template can be stored in the resources folder and can be accessed in the shared library using the libraryResource function.

Here is the list of articles in this shared library series

1. How To Create Jenkins Shared Library For Pipelines

Check out all other Jenkins Tutorials from here – Jenkins Tutorials For Beginners