「Jenkins Pipeline」- 定义共享库

更新日期:2020年03月10日

本文“定义共享库”不是“如何编写共享库”,而是:如何配置 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},然后使用trunkbranches/devtags/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存储库,使用匿名检出。

参考文献



Backlinks: Software Engineering:Continuous Delivery:Jenkins Pipeline:6.Extending with Shared Libraries

ToC

共享库的组成

共享库名称(Name)

源码取回方式(Retrieval method)

可选的版本(Default version)

目录结构

SRC

VARS

RESOURCES

# 其他目录

全局的共享库

文件夹层级的共享库

自动的共享库

参考文献