本文“定义共享库”不是“如何编写共享库”,而是:如何配置 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