Global Pipeline library guide

Shared libraries in Jenkins allow you to centralize and reuse pipeline code across multiple projects. By storing these libraries in Perforce and configuring them in Jenkins, teams can standardize build logic, simplify Jenkinsfiles, and reduce duplication.

Prerequisites

You must install the plugin Pipeline: Shared Groovy Libraries plugin in Jenkins. This plugin is also known as workflow-cps-global-lib. This plugin enables the Global Trusted Pipeline Libraries section in Jenkins’ Configure System page.

Set up Global Pipeline Library

To use your Perforce libraries in Jenkins pipelines, first set them up as a Global Trusted Pipeline Library in the Jenkins system configuration.

1. Go to Manage Jenkins.

2. In the System Configuration section, click on System.

3. Scroll down to Global Trusted Pipeline Libraries.

   This section appears only after installing the Shared Groovy Libraries plugin and is quite far down the page, usually after the Default notification URL section).

4. To set up your Global Pipeline library, click Add.

This enables fields for configuring your Global Pipeline Library. For detailed instructions, see Configure Global Pipeline Library.

Configure Global Pipeline Library

Configure the following fields to set up a Global Pipeline library.

1. Enter a Name, for example my-p4-library. This is how you reference the library in a Jenkinsfile.

2. (Optional) Select Load implicitly to make the library available to all pipelines without explicitly importing it.

3. In Retrieval method, select Legacy SCM.

4. In Source Code Management, select Perforce Software. This will enable several more fields such as Perforce Credentials, Workspace behaviour and Populate options. For information on how to populate these fields, see Pipeline script from SCM setup.

5. In Library Path, enter a path to the library in the Perforce depot. This is covered in more detail in the following section, Library Path

Library Path

The Library Path defines the location of your library inside the Perforce depot. Jenkins uses this path to check out the library code into the pipeline workspace.

For example, the following Utils.groovy file has this depot path: //depot/myLibrary/src/org/example/Utils.groovy

When you have added in the library path, click Save to apply the configuration.

Library Path Tips and Troubleshooting

• You may need to include ${library.<libName>.version} in depot paths to resolve versions correctly.

• Verify that your Perforce workspace view maps only the library depot path. Mismatched views are a common source of errors.

• Keep libraries small and modular, for example, use the vars/ directory for global functions, and src/ for packaged classes.

Use the Library in a Pipeline

Once you have a Global Trusted Pipeline Library configured, here’s how you use it in a pipeline.

1. Open or create a Jenkins Pipeline job

   1. Go to your Jenkins dashboard.

   2. Click New Item, give your job a name, select Pipeline and click OK.

   3. Scroll to the Pipeline section where you can enter your script.

2. Import the library. This is done at the very top of your pipeline script, where you to tell Jenkins which library to use.

   This case, it is @Library('my-p4-library') _

   If you checked Load implicitly when configuring the library, you can skip this step as the library is automatically available.

3. Import a specific class or function from the library. For example, if your library has a Groovy class called Utils in the package org.example

   import org.example.Utils

   Now you can use it in your pipeline.

4. Call a function from the library. This is done inside your pipeline’s script block and you can create an instance of the class and call its functions. For example:

   pipeline {
       agent any
       stages {
           stage('Demo') {
               steps {
                   script {
                       def u = new Utils()  // create the class
                       u.sayHello("Jenkins") // call a function
                   }
               }
           }
       }
   }
   

5. To run the pipeline, click Save and then Build Now. Jenkins will check out the library from Perforce and run your pipeline using the shared code.