Jenkinsfile使用-火龙果软件 - 关心工作者的实践

如果您的SCM插件尚未集成，则可以选择Legacy SCM并选择所提供的任何内容。在这种情况下，您需要${library.yourLibName.version}在SCM的配置中包含某处，以便在结帐时插件将扩展此变量以选择所需的版本。例如，对于Subversion，您可以将Repository URL设置为https://svnserver / project / $ { library . yourLibName . version}，然后使用诸如trunkor branches/dev或之类的版本 tags / 1.0

目录结构

共享库存储库的目录结构如下所示：

(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时，该目录将添加到类路径中。

该vars目录托管定义可从Pipeline访问的全局变量的脚本。通常，每个*.groovy文件的基本名称应该是Groovy（?Java）标识符camelCased。匹配*.txt（如果存在）可以包含通过系统配置的标记格式化程序处理的文档（所以可能真的是HTML，Markdown等，尽管txt需要扩展）。

这些目录中的Groovy源文件与Scripted Pipeline中的“CPS转换”相同。

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

全球共享库

根据用例，有几个可以定义共享库的地方。管理Jenkins?配置系统?全局Pipeline库可以配置所需的许多库。

由于这些库将全局可用，系统中的任何Pipeline都可以利用这些库中实现的功能。

这些库被认为是“受信任的”：他们可以在Java，Groovy，Jenkins内部API，Jenkins插件或第三方库中运行任何方法。这允许您定义将各个不安全的API封装在更高级别的包装器中的库，以便从任何Pipeline使用。请注意，任何能够将提交到该SCM存储库的人都可以无限制地访问Jenkins。您需要总体/ RunScripts权限来配置这些库（通常这将授予Jenkins管理员）。

文件夹级共享库

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

基于文件夹的库不被认为是“受信任的”：它们像Groovy sandbox 一样运行，就像典型的Pipeline一样。

自动共享库

其他插件可能会添加在运行中定义库的方法。例如， GitHub分支源插件提供了一个“GitHub组织文件夹”项，它允许脚本使用不受信任的库，例如github.com/someorg/somerepo没有任何其他配置。在这种情况下，指定的GitHub存储库将从master 分支中使用匿名检出进行加载。

使用库

标记为加载的共享库隐式允许Pipeline立即使用由任何此类库定义的类或全局变量。要访问其他共享库，Jenkinsfile需要使用@Library注释，指定库的名称：

@Library('my-shared-library') _
/* Using a version specifier, such as branch, tag, etc */
@Library('my-shared-library@1.0') _
/* Accessing multiple libraries with one statement */
@Library(['my-shared-library', 'otherlib@abc1234']) _

注释可以在脚本中的任何地方，Groovy允许注释。当引用类库（包含src/目录）时，通常会在import语句上注释：

@Library('somelib')
import com.mycorp.pipeline.somelib.UsefulClass

对于仅定义全局变量（vars/）的共享库或 Jenkinsfile仅需要全局变量的共享库，注释模式@Library('my-shared-library') _可能有助于保持代码简洁。实质上，import该符号不是注释不必要的语句_。

不推荐import使用全局变量/函数，因为这将强制编译器解释字段和方法，static 即使它们是实例。在这种情况下，Groovy编译器可能会产生混乱的错误消息。

在编译脚本之前，在开始执行之前解析和加载库。这允许Groovy编译器了解在静态类型检查中使用的符号的含义，并允许它们在脚本中的类型声明中使用，例如：

@Library('somelib')
import com.mycorp.pipeline.somelib.Helper

int useSomeLib(Helper helper) {
helper.prepare()
return helper.count()
}

echo useSomeLib(new Helper('some text'))

然而，全局变量在运行时解决。

动态加载库

从2.7版Pipeline：共享Groovy库插件，有一个新的选项，用于在脚本中加载（非隐式）库：一个在构建期间的任何时间动态library加载库的步骤。

如果您只对使用全局变量/函数感兴趣（从vars/目录中），语法非常简单：

library 'my-shared-library'

此后，脚本中可以访问该库中的任何全局变量。

从src/目录中使用类也是可能的，但是比较棘手。而在@Library编译之前，注释准备脚本的“classpath”，在library遇到步骤时，脚本已经被编译。因此，您不能import或以其他方式“静态地”引用库中的类型。

但是，您可以动态地使用库类（无类型检查），从library步骤的返回值通过完全限定名称访问它们。 static可以使用类似Java的语法来调用方法：

library('my-shared-library').com.mycorp.

pipeline.Utils.

someStaticMethod()

您还可以访问static字段，并调用构造函数，就像它们是指定的static方法一样new：

def useSomeLib(helper) { // dynamic: cannot

declare as

Helper
helper.prepare()
return helper.count()
}

def lib = library('my-shared-library')

com.mycorp.pipeline // preselect the package

echo useSomeLib(lib.Helper.new(lib.

Constants.SOME_TEXT))

库版本

例如，当勾选“加载隐式”时，或者如果Pipeline仅以名称引用库，则使用配置的共享库的“默认版本” @Library('my-shared-library') _。如果“默认版本” 没有定义，Pipeline必须指定一个版本，例如 @Library('my-shared-library@master') _。

如果在共享库的配置中启用了“允许默认版本被覆盖”，则@Library注释也可以覆盖为库定义的默认版本。这样还可以在必要时从不同的版本加载带有“负载加载”的库。

使用该library步骤时，您还可以指定一个版本：

library 'my-shared-library@master'

由于这是一个常规步骤，所以该版本可以与注释一样计算而不是常量; 例如：

library "my-shared-library@$BRANCH_NAME"

将使用与多分支相同的SCM分支来加载库Jenkinsfile。另一个例子，你可以通过参数选择一个库：

properties([parameters([string(name: 'LIB_VERSION', defaultValue: 'master')])])
library "my-shared-library@${params.LIB_VERSION}"

请注意，该library步骤可能不会用于覆盖隐式加载库的版本。它在脚本启动时已经加载，给定名称的库可能不会被加载两次。

检索方法

指定SCM的最佳方法是使用已经特别更新的SCM插件，以支持新的API来检出任意命名版本（现代SCM选项）。在撰写本文时，Git和Subversion插件的最新版本支持此模式。

传统SCM

尚未更新以支持共享库所需的较新功能的SCM插件仍可通过Legacy SCM选项使用。在这种情况下，包括${library.yourlibrarynamehere.version}可以为该特定SCM插件配置branch / tag / ref的任何位置。这可以确保在检索库的源代码期间，SCM插件将扩展此变量以检出库的相应版本。

动态检索

如果您仅@在library步骤中指定库名称（可选地，随后使用版本），Jenkins将查找该名称的预配置库。（或者在github.com/owner/repo自动库的情况下，它将加载。）

但是您也可以动态地指定检索方法，在这种情况下，不需要在Jenkins中预定义库。这是一个例子：

library identifier: 'custom-lib@master', retriever: modernSCM(
[$class: 'GitSCMSource',
remote: 'git@git.mycorp.com:my-jenkins-utils.git',
credentialsId: 'my-private-key'])

为了您的SCM的精确语法，最好参考流水线语法。

请注意，在这些情况下必须指定库版本。

Writing libraries

在基层，任何有效的 Groovy代码都可以使用。不同的数据结构，实用方法等，如：

// src/org/foo/Point.groovy
package org.foo;

// point in 3D space
class Point {
float x,y,z;
}

访问步骤

库类不能直接调用诸如shor的步骤git。然而，它们可以实现除封闭类之外的方法，这些方法又调用Pipeline步骤，例如：

// src/org/foo/Zot.groovy
package org.foo;

def checkOutFrom(repo) {
git url: "git@github.com:jenkinsci/${repo}"
}

然后可以从脚本Pipeline中调用它：

def z = new org.foo.Zot()
z.checkOutFrom(repo)

这种做法有局限性; 例如，它阻止了超类的声明。

或者，一组steps可以显式传递给库类，构造函数或只是一种方法：

package org.foo
class Utilities implements Serializable {
def steps
Utilities(steps) {this.steps = steps}
def mvn(args) {
steps.sh "${steps.tool 'Maven'}/bin/mvn -o ${args}"
}
}

当在类上保存状态时，如上面所述，类必须实现 Serializable接口。这样可确保使用该类的Pipeline，如下面的示例所示，可以在Jenkins中正确挂起并恢复。

@Library('utils') import org.foo.Utilities
def utils = new Utilities(steps)
node {
utils.mvn 'clean package'
}

如果库需要访问全局变量，例如env，那些应该以类似的方式显式传递给库类或方法。

而不是将许多变量从脚本Pipeline传递到库中，

package org.foo
class Utilities {
static def mvn(script, args) {
script.sh "${script.tool 'Maven'}/bin/mvn -s ${script.env.HOME}/jenkins.xml -o ${args}"
}
}

上面的示例显示了脚本被传递到一个static方法，从脚本Pipeline调用如下：

@Library('utils') import static org.foo.Utilities.*
node {
mvn this, 'clean package'
}

定义全局变量

在内部，vars目录中的脚本作为单例按需实例化。这允许在单个.groovy文件中定义多个方法或属性，这些文件彼此交互，例如：

// vars/acme.groovy
def setName(value) {
name = value
}
def getName() {
name
}
def caution(message) {
echo "Hello, ${name}! CAUTION: ${message}"
}

在上面，name不是指一个字段（即使你把它写成this.name！），而是一个根据需要创建的条目Script.binding。要清楚你要存储什么类型的什么数据，你可以改为提供一个明确的类声明（类名称应符合的文件名前缀，如果只能调用Pipeline的步骤steps或this传递给类或方法，与src上述课程一样）：

// vars/acme.groovy
class acme implements Serializable {
private String name
def setName(value) {
name = value
}
def getName() {
name
}
def caution(message) {
echo "Hello, ${name}! CAUTION: ${message}"
}
}

然后，Pipeline可以调用将在acme对象上定义的这些方法：

acme.name = 'Alice'
echo acme.name /* prints: 'Alice' */
acme.caution 'The queen is angry!' /* prints: 'Hello, Alice. CAUTION: The queen is angry!' */

温习提示：在Jenkins加载并使用该库作为成功的Pipeline运行的一部分后，共享库中定义的变量将仅显示在“ 全局变量参考”（在“ Pipeline语法”下）。

定义步骤

共享库还可以定义与内置步骤类似的全局变量，例如sh或git。共享库中定义的全局变量必须使用所有小写或“camelCase”命名，以便由Pipeline正确加载。

例如，要定义sayHello，vars/sayHello.groovy 应该创建文件，并应该实现一个call方法。该call方法允许以类似于以下步骤的方式调用全局变量：

// vars/sayHello.groovy
def call(String name = 'human') {
// Any valid steps can be called from this code, just like in other
// Scripted Pipeline
echo "Hello, ${name}."
}

然后，Pipeline将能够引用并调用此变量：

如果调用一个块，该call方法将收到一个 Closure。应明确界定类型，以澄清步骤的意图，例如：

// vars/windows.groovy
def call(Closure body) {
node('windows') {
body()
}
}

然后，Pipeline可以像接受一个块的任何内置步骤一样使用此变量：

windows {
bat "cmd /?"
}

定义更结构化的DSL

如果您有大量类似的Pipeline，则全局变量机制提供了一个方便的工具来构建更高级别的DSL来捕获相似性。例如，所有的插件Jenkins构建和以同样的方式进行测试，所以我们可以写一个名为步 buildPlugin：

// vars/buildPlugin.groovy
def call(body) {
// evaluate the body block, and collect configuration into the object
def config = [:]
body.resolveStrategy = Closure.DELEGATE_FIRST
body.delegate = config
body()

// now build, based on the configuration provided
node {
git url: "https://github.com/jenkinsci/${config.name}-plugin.git"
sh "mvn install"
mail to: "...", subject: "${config.name} plugin build", body: "..."
}
}

假设脚本已被加载为全局共享库或文件夹级共享库，结果Jenkinsfile将会更加简单：

Jenkinsfile (Scripted Pipeline)
buildPlugin {
name = 'git'
}

使用第三方库

通过使用注释，可以使用通常位于Maven Central中的第三方Java库从受信任的库代码中使用@Grab。有关详细信息，请参阅 Grape文档，但简单地说：

@Grab('org.apache.commons:commons

-math3:3.4.1')
import org.apache.commons.math3.primes.

Primes
void parallelize(int count) {
if (!Primes.isPrime(count)) {
error "${count} was not prime"
}
// …
}

第三方库默认缓存~/.groovy/grapes/在Jenkins主机上。

资源加载

外部库可以resources/使用libraryResource步骤从目录中加载附件文件。参数是一个相对路径名，类似于Java资源加载：

def request = libraryResource 'com/mycorp/pipeline/somelib/request.json'

该文件作为字符串加载，适合传递给某些API或使用保存到工作空间writeFile。