Skip to main content
This lesson assumes a Shared Library repository has already been created. Here we’ll configure that library in Jenkins so Pipeline jobs can fetch and use its reusable steps, classes, and resources. For detailed, guided steps and screenshots, see the official Jenkins Shared Libraries documentation: Example: a simple library step that sends a Slack notification
How pipelines fetch a shared library
  • To make the library available to Pipelines, you must register it in Jenkins under Global Pipeline Libraries.
Steps to register a shared library:
  1. Open the Jenkins UI and go to Manage Jenkins → Configure System (or search for “Global Pipeline Libraries” on the Manage Jenkins page).
  2. Locate the Global Pipeline Libraries section and click Add to create a new library entry.
  3. Provide the repository and retrieval settings described below, then click Apply / Save.
Two main library trust models
  • Global trusted pipeline libraries — run without the Groovy sandbox, suitable for libraries you control and maintain.
  • Global untrusted pipeline libraries — executed inside Jenkins’ Groovy sandbox; any non-whitelisted method calls require admin approval via the Script Security plugin.
Use trusted libraries for code you fully control to avoid sandbox restrictions. Use untrusted libraries for external or third-party code until you approve specific methods via the Script Security plugin.
Sandbox behavior and an example error
  • The Groovy sandbox blocks certain operations for safety. When a sandboxed script uses blocked methods, Jenkins logs a RejectedAccessException and an admin must whitelist the required methods.
Example sandbox error when an unapproved static method is invoked:
What to configure when adding a library
  • When adding a Global Pipeline Library, fill in these core fields:
Common option checkboxes and what they do:
  • Load implicitly — pipelines can use the library without an @Library annotation.
  • Allow default version to be overridden — pipelines may specify a different version with @Library("name@branch").
  • Include library changes in job recent changes — shows library updates in the job change history.
  • Cache retrieved versions on the controller — speeds up fetches by caching artifacts on the controller.
Configure the Git endpoint (public repos do not require credentials). Click Apply/Save to persist the configuration.
A screenshot of the Jenkins "Manage Jenkins > System" configuration page showing the "Retrieval method: Modern SCM" section with a Source Code Management dropdown (Git, GitHub, Gitea) — the Git option is highlighted and the Credentials and Save/Apply buttons are visible.
Using the library inside a Pipeline
  • Once the library is registered, pipelines can load it via the @Library annotation or, if enabled, use it implicitly.
Explicit @Library usage:
You can also enable changelog capture and allow version overrides:
If you checked “Load implicitly” when registering the library, pipelines do not need the @Library annotation — the library’s steps and classes are available automatically.
Using third-party Java libraries (Maven) inside a trusted library
  • Trusted shared libraries can fetch external JARs using @Grab. This requires the library to be trusted (not sandboxed).
Example using Apache Commons Math inside a trusted library:
Maven dependency coordinates (example):
@Grab only works for trusted libraries. Fetching arbitrary jars and executing code from them may require operations that are blocked by the sandbox and will require admin approval via the Script Security plugin.
Example: we registered this repository as a Global Trusted Shared Library
  • Because this library is trusted, it will run without sandbox restrictions and can use @Grab, libraryResource, and other features that might be restricted in sandboxed libraries.
A screenshot of the Jenkins "Global Trusted Pipeline Libraries" settings page showing a configured library named "dasher-trusted-shared-library" with default version "main" and various checkboxes and retrieval options. The Save and Apply buttons are visible at the bottom.
Links and references If you run into permission issues or blocked method errors, review the Script Security approval queue and consider whether the library should be marked as trusted or if specific methods need to be whitelisted.

Watch Video