Child pages
  • Pipeline Shared Groovy Libraries Plugin

Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View Pipeline: Shared Groovy Libraries on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

Provides capability to extend pipeline scripts using shared libraries.

When you have multiple Pipeline jobs, you often want to share common parts of the Pipeline scripts to keep them DRY. A typical use case is that you have many projects that are built in the similar way.

This plugin adds that functionality by allowing you to create “shared library script” SCM repositories. It can be used in two modes:

  • A legacy mode in which there is a single Git repository hosted by Jenkins itself, to which you may push changes;
  • A more general mode in which you may define libraries hosted by any SCM in a location of your choice.

Comprehensive user documentation can be found in the Pipeline chapter of the User Handbook.

A component of Pipeline Plugin.

Source code

Configure plugin via Groovy script

Either automatically upon Jenkins post-initialization or through Jenkins script console, example:


// imports
import hudson.scm.SCM
import jenkins.model.Jenkins
import jenkins.plugins.git.GitSCMSource
import org.jenkinsci.plugins.workflow.libs.*
import org.jenkinsci.plugins.workflow.libs.LibraryConfiguration
import org.jenkinsci.plugins.workflow.libs.SCMSourceRetriever

// parameters
def globalLibrariesParameters = [
  branch:               "master",
  credentialId:         "global-shared-library-key",
  implicit:             false,
  name:                 "Your Global Shared Library name here",
  repository:           ""

// define global library
GitSCMSource gitSCMSource = new GitSCMSource(

// define retriever
SCMSourceRetriever sCMSourceRetriever = new SCMSourceRetriever(gitSCMSource)

// get Jenkins instance
Jenkins jenkins = Jenkins.getInstance()

// get Jenkins Global Libraries
def globalLibraries = jenkins.getDescriptor("org.jenkinsci.plugins.workflow.libs.GlobalLibraries")

// define new library configuration
LibraryConfiguration libraryConfiguration = new LibraryConfiguration(, sCMSourceRetriever)

// set new Jenkins Global Library

// save current Jenkins state to disk


2.14 (Jul 11, 2019)

  • JENKINS-43802 - Make folder-scoped credentials work correctly with shared libraries.
  • JENKINS-44892 - Do not add a UUID parameter when constructing the library step on the Pipeline Syntax page.
  • Fix: (PR 63) - Support for SCM retry count did not retry the checkout attempt for certain kinds of errors when it should have. 
  • Internal: (PR 66) - Do not add nullability annotations to primitive types.
  • Internal: (PR 67PR 70PR 73) - Dependency and test updates, new integration tests for issues fixed in upstream plugins.

2.13 (Feb 1, 2019)

  • Fix: (PR 59) - Support for SCM retry count added in 2.12 did not apply to some SCM operations.
  • Internal: (PR 57) - Avoid use of deprecated APIs.
  • Internal: (PR 44, PR 56) - Add additional tests and update tests to run correctly on Windows

2.12 (Oct 2, 2018)

  • Fix: JENKINS-40109 - Make compilation errors in shared libraries serializable so that the actual compilation error is reported instead of a NotSerializableException in some cases.
  • Improvement: Implement support for SCM retry count.

2.11 (Sep 8, 2018)

  • JENKINS-53485 - Fix a file leak introduced in version 2.10 of this plugin affecting all uses of the libraryResource step.

2.10 (Aug 21, 2018)

  • Important: As of this release, the plugin requires Java 8 and Jenkins 2.60.3 or newer.
  • JENKINS-52313 - Add an optional encoding argument to the libraryResource step. Base64 is a supported encoding, and will cause the resource to be loaded as a Base64-encoded string, which is useful for copying binary resources such as images when combined with Pipeline: Basic Steps 2.8.1 or higher.

2.9 (Sept 13, 2017)

  • JENKINS-41497 - allow excluding shared libraries from changelogs (and therefore from SCM polling as well) via global configuration option and/or @Library(value="some-lib@master", changelog=false).

2.8 (Apr 24, 2017)

  • Fixing some bugs affecting Windows-based masters (agent platform irrelevant):
    • improper handling of CRNL in *.txt global variable help files
    • incorrect display of class names in Replay when using class libraries
    • failure of class library access from library step depending on filesystem canonicalization

2.7 (Mar 03, 2017)

  • JENKINS-39450 Added a library step as a dynamic alternative to @Library used since 2.3.

2.6 (Feb 10, 2016)

2.5 (Nov 21, 2016)

  • Related to JENKINS-38517, checking out distinct libraries each into their own local workspaces, and improving parallelism in the case of concurrent builds.

2.4 (Oct 05, 2016)

  • JENKINS-38550 The Modern SCM option should not be shown unless some matching plugin is actually installed.
  • JENKINS-38712 Library configuration screens used deep horizontal indentation.
  • JENKINS-38048 Obsolete query parameter caused a warning in the JavaScript console.

2.3 (Sep 07, 2016)

  • JENKINS-31155 New system of external shared libraries.
  • JENKINS-26192 Supporting Grape (the @Grab annotation) from global shared libraries (internal or external).

2.2 (Aug 09, 2016)

  • JENKINS-34650 Global library code now runs without the Groovy sandbox, so may provide safe encapsulations of privileged operations such as Jenkins API accesses. (Pushes to the library always required Overall/RunScripts anyway.)
  • JENKINS-34008 API allowing plugins to be notified of changes to the library.

2.1 (Jun 30, 2016)

  • JENKINS-34517 Use of global variables from the shared library would result in errors when resuming a build.

2.0 (Apr 05, 2016)

  • First release under per-plugin versioning scheme. See 1.x changelog for earlier releases.


  1. Unknown User (elordahl)

    Unknown User (jglick) Is it possible to define Global Pipeline Libraries without having their changes trigger builds of dependent jobs?  I would like the jobs to utilize the changes, but not until the next build.  Currently, each change to the global library [repository] triggers a large number of jobs, which is not ideal.


    1. Unknown User (neybar)

      We are having the same issue.  It is starting to get out of hand for us.  If we merge a change to our master branch for the shared library, then it will kick off all of our jobs that use the library.  It causes further problems because it will start so many jobs that we end up running out of executors, which then becomes a manual cleanup.  There is a setting for the libraries called 'Include @Library changes in job recent changes' which we have unchecked, but that doesn't seem to be respected.

      We are currently on Jenkins 2.82 and 2.9 of the groovy libraries plugin

  2. Unknown User (it12lsp)


    is it possible to use global shared libraries for JSON Parameter Config Groovy Script?



  3. Unknown User (nachevn)

    Hi, is it possible to checkout the shared library not on the master node? This is always the default behavior but I'm currently trying to prevent the execution on the master, because of the different teams on our Jenkins server? How can I change it to another slave node?



  4. Unknown User (jon_es)


    would it be possible to additionally specify the path to the root of the library, where var, src and resource folders are located? We have a unified repository and we can not have these folders in the root of our repository.



  5. Unknown User (myamoto)


    I'm not sure if that's the best place for that, so feel free to LMK if there's a forum or something I could put that on.

    We are using your plugin and implemented workflow on different project types with groovy code.

    We are encountering an issue which seem class-loading related.

    Using an instance of "JAXBContext" in our shared library leads to some weird behavior.

    The class gets loaded from some other plugin installed on our jenkins.

    At some point it was loaded from deployit-plugin (jenkins/plugins/deployit-plugin/web-inf/lib/jaxb-impl-xxx.jar).

    After installing xlrelease-plugin (xlrelease-plugin/web-inf/lib/jaxb-impl-xxx.jar), it seems that JAXBContext is now loaded from this plugin and we don't get "ClassCastException" anymore.

    We have no clue as to why it would be loaded from either of those plugins.

    I looked a bit at your code on github. As expected there's some class loader manipulation.

    But I didn't find any pointer to the relations with the class loaders of other plugins.

    If I understood correctly what's stated in there :

    "workflow-cps-global-lib" should like others jenkins plugins inherit the java libraries (jars) that are loaded by plugins it depends on.

    But your plugin does not depend on xlrelease-plugin or deployit-plugin.

    If you could give me infos on why I get those classes loaded it would be very helpful.

    Best regards

    1. Unknown User (jglick)

      We try not to use comments in Confluence (not sure if they can simply be disabled). Use the Jenkins users’ list, IRC, Gitter,, etc.