「Jenkins Pipeline」- 定义共享库 @20210130

本文“定义共享库”不是“如何编写共享库”，而是：如何配置 Jenkins 来加载某个共享库，以便在 Jenkinsfile 中引用。

共享库的组成

共享库由三部分组成：（1）共享库名称；（2）源码取回方式；（3）可选的版本

共享库名称（Name）

共享库名称是共享库的简短标识，每个共享库都具有自己的名字。在 Jenkinsfile 中，将通过该名称引用特定的共享库。

源码取回方式（Retrieval method）

共享库保存在单独的仓库中，在执行之前需要先通过 SCM 取回。指定 SCM 的最佳方法是使用 SCM Plugin ，那些插件经过专门更新以支持“用于检出任意命名版本的”新API（使用 Modern SCM 选项）。目前 GIT 和 SVN 支持该模式。

如果你使用的 SCM Plugin 尚未集成，可以选择Legacy SCM选项，并选择所提供的任何内容。在这种情况下，需要在 SCM Plugin 的配置中包含$ {library.yourLibName.version}，以便在检出时 SCM Plugin 将扩展此变量以选择所需的版本。例如对于 Subversion 插件，可以将存储库 URL 设置为svnserver/project/${library.yourLibName.version}，然后使用trunk或branches/dev或tags/1.0等版本。

可选的版本（Default version）

从仓库中取回共享库时，可以指出特定版本。”可选的版本“可以是能够被 SCM 识别的任何东西（比如 GIT 的分支，标签，提交等等）。你也可以声明脚本是否需要明确要求该库，或在默认情况下是否存在。此外如果在 Jenkins 配置中指定某个版本，可以防止脚本使用其他版本。

目录结构

(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

SRC

像标准的 Java 源码目录结构。执行 Pipeline 时，此目录将添加到 CLASSPATH 中。

VARS

保存脚本文件，将在 Pipeline 中作为变量公开，文件名将是在 Pipeline 中变量的名称。什么意思呢？如果你有一个名为vars/log.groovy的文件，其中包含def info（message）{}方法，那么可以在 Pipeline 中访问此函数，例如log.info "hello world"。可以在此文件中放置任意数量的函数。请阅读下面的更多示例和选项。

每个.groovy文件的基本名称应该是一个Groovy（~Java）标识符，通常是驼峰命名。可以存在对应的.txt文件，它其中可以包含文档，通过系统配置的「标记格式化程序」处理（因此可能是HTML，Markdown等，但需要.txt扩展名）。此文档仅在「全局变量引用」页面上可见，可以从“导入共享库”的“ Pipeline 作业”的“导航侧栏”进行访问。此外这些作业必须“在生成共享库文档之前”成功运行一次。

这些目录中的 Groovy 源文件与 Scripted Pipeline 获得相同的“CPS transformation”。

RESOURCES

允许使用libraryResource步骤，来从外部库加载关联的非Groovy文件。 目前，内部库不支持此功能。

# 其他目录

其他目录为保留目录，用于以后增强扩展。

全局的共享库

在何处配置：Manage Jenkins » Configure System » Global Pipeline Libraries 。

可以在多出定义共享库，取决以使用场景。

该共享库是全局的，在系统中的任何 Pipeline 可以使用该库中实现的功能。

这些库被视为可信的，他们可以运行在Java、Groovy、Jenkin内部API、Jenkins插件、第三方库中的任何方法。可以使用该特性将不安全的API封装在高级的包装器中，以便在任何Pipeline中使用。任何可以推送代码到该共享库的成员可以获得访问 Jenkins 的无限权限。需要 Overall/RunScripts 权限来配置这些共享库，通常管理员具有该权限。

文件夹层级的共享库

在何处配置：在特定项目中进行配置。

创建的任何文件夹都可以具有与之关联的共享库。此机制允许将特定库的范围限定为文件夹或子文件夹内的所有 Pipeline 。

基于文件夹的库不被视为“受信任”，它们在 Groovy Sandbox 中运行，就像典型的Pipeline一样。

自动的共享库

其他插件可能会添加“定义动态定义库的”方法。 例如 GitHub Branch Source 插件提供了一个 GitHub Organization Folder 项，该项允许脚本使用不受信任的库，例如 github.com/someorg/somerepo，无需任何其他配置。在这种情况下，从master分支加载指定的GitHub存储库，使用匿名检出。

参考文献

WikiNotes/定义共享库
Extending with Shared Libraries