官方文檔 - Extending with Shared Libraries
CloudBees - getting-started-with-shared-libraries-in-jenkins
CloudBees - github - pipeline-library
CloudBees - github - global-library-課程范例
How To Use Shared Libraries In A Jenkins Pipeline?
一枪狂、Shared Libraries 簡(jiǎn)介
1细疚、Directory structure
Shared Library repository 的結(jié)構(gòu)
(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目錄類似標(biāo)準(zhǔn)的Java源目錄茄唐。在執(zhí)行Pipeline的時(shí)候會(huì)被添加到classpath芋肠。 -
vars目錄存放腳本文件，這些文件在Pipelines中作為變量幽崩。文件的名稱就是Pipeline中變量的名稱苦始。比如存在文件vars/log.groovy，文件下存在函數(shù)def info(message)…慌申，那么在Pipeline以log.info "hello world"的方式訪問(wèn)盈简。 -
resources目錄允許擴(kuò)展庫(kù)使用libraryResourcestep 加載非Groovy文件。目前內(nèi)部庫(kù)不支持此功能太示。參考Loading resources柠贤。
2、Global Shared Libraries
- 推薦方式
- 通過(guò)
Manage Jenkins ? System ? Global Pipeline Libraries進(jìn)行配置类缤，然后在pipeline調(diào)用臼勉。詳情參見下文 使用 libraries
3、Folder-level Shared Libraries
https://stackoverflow.com/questions/37800195/how-do-you-load-a-groovy-file-and-execute-it
或許有其他使用方法餐弱，如下范例是文件級(jí)別宴霸，并非目錄級(jí)別的共享庫(kù)囱晴。
范例
- 創(chuàng)建測(cè)試groovy文件
/opt/jenkins_library_test/Tools.groovy
public class Demo {
String message;
Demo(String message) {
this.message = message;
}
public void print(def script) {
script.sh "echo " + message
}
}
Demo createDemo(String message) {
new Demo(message)
}
return this
- 編輯pipeline script
聲明式 pipeline 如下
pipeline {
agent any
stages {
stage('Hello') {
steps {
echo 'Hello World'
}
}
stage('Demo stage') {
steps {
script {
Object lib = load '/opt/jenkins_library_test/Tools.groovy'
Object demo = lib.createDemo('a demo')
demo.print(this)
}
}
}
}
}
腳本式pipeline 如下
node {
stage('Hello') {
echo 'Hello World'
}
stage('Demo stage') {
script {
Object lib = load '/opt/jenkins_library_test/Tools.groovy'
Object demo = lib.createDemo('a demo')
demo.print(this)
}
}
}
-
執(zhí)行結(jié)果如下
image.png
4、Automatic Shared Libraries
其他插件有更多動(dòng)態(tài)定義庫(kù)的方法瓢谢。如 Pipeline: GitHub Groovy Libraries 插件畸写，允許無(wú)需配置即可使用不可信任的庫(kù)，比如github.com/someorg/somerepo氓扛。指定庫(kù)會(huì)以匿名 checkout 的方式 從 master 分支加載枯芬。
二、使用 libraries
1采郎、常規(guī)調(diào)用
Jenkinsfile 使用 @Library 標(biāo)識(shí)符千所，加 library 的名字，來(lái)進(jìn)行調(diào)用蒜埋。示例如下：
@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']) _
@Library('somelib')
import com.mycorp.pipeline.somelib.UsefulClass
當(dāng)引用
class library（src/目錄）時(shí)淫痰，@注釋需要在import語(yǔ)句上面
annotation 幫助文檔
對(duì)于只定義了全局變量 Global Variables (vars/) 的 Shared Libraries，或只需要全局變量的 Jenkinsfile整份， @Library('my-shared-library') _ 的注釋格式有助于保持代碼簡(jiǎn)潔待错。本質(zhì)上，是注釋 _烈评，而非不必要的 import 火俄。
不建議 import 全局變量/函數(shù)，即便是實(shí)例础倍，這也會(huì)強(qiáng)迫編譯器將字段和方法解釋為 static ，這種情況下 Groovy compiler 會(huì)報(bào)錯(cuò)胎挎。
Libraries 在腳本執(zhí)行前的編譯過(guò)程被解析沟启、加載。這就允許 Groovy compiler 在靜態(tài)類型檢查時(shí)理解所使用符號(hào)的含義犹菇，并允許它們?cè)谀_本中的類型聲明中使用德迹，例如：
這允許Groovy編譯器理解靜態(tài)類型檢查中使用的符號(hào)的含義，并允許它們?cè)谀_本中的類型聲明中使用揭芍，例如：
@Library('somelib')
import com.mycorp.pipeline.somelib.Helper
int useSomeLib(Helper helper) {
helper.prepare()
return helper.count()
}
echo useSomeLib(new Helper('some text'))
Global Variables 在 runtime 中被解析胳搞。
2、動(dòng)態(tài)加載 Loading libraries dynamically
自插件 Pipeline: Shared Groovy Libraries 2.7 版本后称杨，有一種動(dòng)態(tài)加載library的方法（library step ）肌毅。
官方描述不嚴(yán)謹(jǐn)。
Pipeline: Shared Groovy Libraries已退役姑原，代替以 Pipeline: Groovy Libraries悬而。
參見說(shuō)明文檔：https://plugins.jenkins.io/workflow-cps-global-lib/
library 'my-shared-library'
然后，腳本就可以訪問(wèn)該 library 中的任何全局變量了锭汛。
訪問(wèn) src/ 目錄下的 class 也可以笨奠，略麻煩袭蝗。@Library 在編譯前已經(jīng)設(shè)定好了 classpath，到library step的時(shí)候腳本已經(jīng)編譯完畢了般婆。因此到腥，不能import或static類型引用。
但是蔚袍，您可以動(dòng)態(tài)地使用 library classes（不進(jìn)行類型檢查）乡范，通過(guò) library step 返回值中的完全限定名稱來(lái)訪問(wèn)。靜態(tài)方法可以通過(guò)類似Java的語(yǔ)法調(diào)用：
library('my-shared-library').com.mycorp.pipeline.Utils.someStaticMethod()
當(dāng)使用 new 的靜態(tài)方法時(shí)页响，也是可以訪問(wèn)靜態(tài)字段篓足，并調(diào)用構(gòu)造函數(shù)的：
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))
3、版本設(shè)定 Library versions
@Library('my-shared-library') _
@Library('my-shared-library@master') _
library 'my-shared-library@master'
library "my-shared-library@$BRANCH_NAME"
# 根據(jù)傳遞的參數(shù)設(shè)定版本
properties([parameters([string(name: 'LIB_VERSION', defaultValue: 'master')])])
library "my-shared-library@${params.LIB_VERSION}"
4闰蚕、獲取庫(kù)的方法 Retrieval Method
- 使用 Modern SCM 栈拖，僅當(dāng)老版本不支持Shared Libraries的新特性時(shí)使用 Legacy SCM 。
Jenkins -- 系統(tǒng)管理 -- 系統(tǒng)配置 -- Global Pipeline Libraries
Sharable libraries available to any Pipeline jobs running on this system. These libraries will be trusted, meaning they run without “sandbox” restrictions and may use @Grab.
范例：
Name： cloudbee-sample-library
項(xiàng)目倉(cāng)庫(kù)： https://github.com/darinpope/github-api-global-lib
如果library step指定了library名稱没陡，Jenkins將查找該名稱的預(yù)配置庫(kù)涩哟。
也可以指定動(dòng)態(tài)檢索方法，無(wú)需在Jenkins中預(yù)先配置盼玄。
如下范例：
library identifier: 'custom-lib@master', retriever: modernSCM(
[$class: 'GitSCMSource',
remote: 'git@git.mycorp.com:my-jenkins-utils.git',
credentialsId: 'my-private-key'])
該方式必須指定版本
更多關(guān)于SCM的語(yǔ)法贴彼，參考 Pipeline Syntax
5、范例
配置 Global Share Libraries 如下：
Name： cloudbee-sample-library
項(xiàng)目倉(cāng)庫(kù)： https://github.com/darinpope/github-api-global-lib
pipeline script
library 'cloudbee-sample-library'
node {
stage('test') {
helloWorld(name:"Darin", dayOfWeek:"Tuesday")
}
}
修改如下
library 'cloudbee-sample-library@main'
這邊的分支是 main 埃儿， 不是 master器仗。繼續(xù)執(zhí)行，如圖童番。
三精钮、編寫 libraries
略
