Shared pipeline libraries in Jenkins

Updated:

Shared pipeline libraries in Jenkins

You’re getting up to speed with Jenkins now and you’re mastering the art of the pipeline. But now you’ve got a few projects up and running, how do you avoid repeating the same common code across different pipelines?

I often write code that I know will be reused across several different pipelines in Jenkins. For example, if you’re already writing code in your pipelines to do any of these:

  • perform a deployment
  • check the current environment
  • parse a file
  • do a compliance check of the application

…then you’re probably going to be better off putting the code for these into a shared library, so that lots of different projects can use them.

Copying and pasting the same code into different pipelines can quickly become a maintenance headache.

So to avoid this, you store your “reusable bits” (technical term!) in a Shared Library in Jenkins. You only need to write some code once, and then you can reference the same code in all of your pipelines.

Over time, you’ll build up a collection of these reusable functions in your Library.

So how do you write a Pipeline library function (or step)

Pipeline library functions (called steps) are written in the Groovy language. You’ve already used Groovy in Jenkins. It’s a Java-based scripting language, with a very easy, flexible syntax.

Most things you can do in Java, you can do in Groovy. If you want to start learning Groovy, then you can find some learning resources here.

A shared library is simply a collection of independent Groovy scripts which can be referenced from your Jenkinsfile at runtime. And the best part is, the Library can be stored – like everything else – in a repository inside Git. This means you can version, tag, and do all the stuff you’re used to with Git.

You just need to set up your Library first. Setting up a shared library is fairly easy, and this post I’ll show you how, with a quick example.

A Jenkins shared library example

  1. Create the shared library

    First you need to create a Git repository which will contain your library of functions (steps). You can also use Subversion.

    In your repository, create a directory called vars. This will hold your custom steps. Each of them will be a different .groovy file underneath your vars directory, e.g.:

    vars/
        deployApp.groovy
        parseFile.groovy
        sayHello.groovy
        readCredentials.groovy
        doComplianceCheck.groovy
    

    I’m using Git to store my repository. I’ve created a sample repo on GitHub, which includes one function, the sayHello example from the official Jenkins documentation.

    See the example repository on GitHub

  2. Add your custom steps

    Each of your custom steps is a different .groovy file inside your vars/ directory. In Jenkins terminology, these are called Global Variables, which is why they are located inside vars/.

    Create a file for your custom step, and fill in the code. For example, a simple greeting function would look like this:

    #!/usr/bin/env groovy
    
    def call(String name = 'human') {
      echo "Hello, ${name}."
    }
    

    Notice how the Groovy script must implement the call method. Then you should write your custom code within the braces { }. You can also add parameters to your method - the example above has one parameter name, with a default value of human.

  3. Set up the library in Jenkins

    Now you’ve created your library with custom steps, you need to tell Jenkins about it.

    You can define a shared library within a Jenkinsfile, or you can configure the library using the Jenkins web console. I think it’s better to add from the web console, because you then you can share the library across all of your build jobs.

    To add your shared library (I’m using my demo on GitHub as an example):

    In Jenkins, go to Manage Jenkins → Configure System. Under Global Pipeline Libraries, add a library with the following settings:

    • Name: pipeline-library-demo
    • Default version: Specify a Git reference (branch or commit SHA), e.g. master
    • Retrieval method: Modern SCM
    • Select the Git type
    • Project repository: https://github.com/monodot/pipeline-library-demo.git
  4. Use the library in a pipeline

    To use the shared library in a pipeline, you just add @Library('your-library-name') to the top of your pipeline definition, or Jenkinsfile. Then call your step by name, e.g. sayHello:

    @Library('pipeline-library-demo')_
    
    stage('Demo') {
        echo 'Hello world'
        sayHello 'Dave'
    }
    

    NOTE: The underscore (_) is not a typo! You need this underscore if the line immediately after the @Library annotation is not an import statement.

    If you run the pipeline above, then the output should look something like this:

    Jenkins job output

TL;DR?

That’s it for my intro to Shared Libraries in Jenkins! As you can see they’re a useful way to share common code that you might use across different Jenkinsfiles. Here’s some things to remember:

  • You should use Groovy to write your custom functions or steps
  • Steps are called Global Variables in Jenkins terminology, and they should be placed inside a vars/ directory in your repository
  • Your custom step should implement the def call() method; you can also define parameters to your step
  • Add your shared library using the Configure System screen in Jenkins

Thanks for reading! How are you using Jenkins pipelines? Any feedback on this article? You’re very welcome to post your thoughts in the comments section below.

Leave a Comment