A Shared Library is defined with a name, a source code retrieval method such
as by SCM, and optionally a default version. The name should be a short
identifier as it will be used in scripts.
The version could be anything understood by that SCM; for example, branches,
tags, and commit hashes all work for Git. You may also declare whether scripts
need to explicitly request that library (detailed below), or if it is present
by default. Furthermore, if you specify a version in Jenkins configuration,
you can block scripts from selecting a different version.
The best way to specify the SCM is using an SCM plugin which has been
specifically updated to support a new API for checking out an arbitrary named
version (Modern SCM option). As of this writing, the latest versions of the
Git and Subversion plugins support this mode; others should follow.
If your SCM plugin has not been integrated, you may select Legacy SCM and
pick anything offered. In this case, you need to include
${library.yourLibName.version}
somewhere in the configuration of the SCM, so
that during checkout the plugin will expand this variable to select the desired
version. For example, for Subversion, you can set the Repository URL to
svnserver/project/${library.yourLibName.version}
and then use
versions such as trunk
or branches/dev
or tags/1.0
.
Directory structure
The directory structure of a Shared Library repository is as follows:
(root)
+- src # Groovy source files
| +- org
| +- foo
| +- Bar.groovy # for org.foo.Bar class
+- vars
| +- foo.groovy # for global 'foo' variable
| +- foo.txt # help for 'foo' variable
+- resources # resource files (external libraries only)
| +- org
| +- foo
| +- bar.json # static helper data for org.foo.Bar
The src
directory should look like standard Java source directory structure.
This directory is added to the classpath when executing Pipelines.
The vars
directory hosts script files that are exposed as a variable in Pipelines. The name of the file is the name of the variable in the Pipeline.
So if you had a file called vars/log.groovy
with a function like def info(message)…
in it, you can access this function like log.info "hello world"
in the Pipeline. You can put as many functions as you like inside this file. Read on below for more examples and options.
The basename of each .groovy
file should be a Groovy (~ Java) identifier, conventionally camelCased
.
The matching .txt
, if present, can contain documentation, processed through the system’s configured markup formatter (so may really be HTML, Markdown, etc., though the .txt
extension is required). This documentation will only be visible on the Global Variable Reference pages that are accessed from the navigation sidebar of Pipeline jobs that import the shared library. In addition, those jobs must run successfully once before the shared library documentation will be generated.
The Groovy source files in these directories get the same “CPS transformation”
as in Scripted Pipeline.
A resources
directory allows the libraryResource
step to be used from an external library to load associated non-Groovy files.
Currently this feature is not supported for internal libraries.
Other directories under the root are reserved for future enhancements.
Global Shared Libraries
There are several places where Shared Libraries can be defined, depending on
the use-case. Manage Jenkins » Configure System » Global Pipeline Libraries
as many libraries as necessary can be configured.
Since these libraries will be globally usable, any Pipeline in the system can
utilize functionality implemented in these libraries.
These libraries are considered "trusted:" they can run any methods in Java,
Groovy, Jenkins internal APIs, Jenkins plugins, or third-party libraries. This
allows you to define libraries which encapsulate individually unsafe APIs in a
higher-level wrapper safe for use from any Pipeline. Beware that anyone able to
push commits to this SCM repository could obtain unlimited access to Jenkins.
You need the Overall/RunScripts permission to configure these libraries
(normally this will be granted to Jenkins administrators).
Folder-level Shared Libraries
Any Folder created can have Shared Libraries associated with it. This mechanism
allows scoping of specific libraries to all the Pipelines inside of the folder
or subfolder.
Folder-based libraries are not considered "trusted:" they run in the Groovy
sandbox just like typical Pipelines.
Automatic Shared Libraries
Other plugins may add ways of defining libraries on the fly. For example, the
GitHub Branch Source plugin provides a "GitHub
Organization Folder" item which allows a script to use an untrusted library
such as github.com/someorg/somerepo
without any additional configuration. In
this case, the specified GitHub repository would be loaded, from the master
branch, using an anonymous checkout.