使用 Jenkins 共享库

简介

Jenkins 共享库（Shared Libraries）允许团队在多个任务中复用流水线代码。一种常见的库布局是将自定义的简单步骤放置在 vars/ 目录下。流水线随后可以加载该库，并像调用普通的流水线函数一样调用这些步骤。

在本实验中，你将准备一个包含 vars/sayHello.groovy 的本地共享库，从 Jenkins 仪表板将其注册为全局流水线库，创建一个调用 sayHello 的流水线任务，并在 Jenkins 中验证输出结果。

准备共享库仓库

在此步骤中，你将为 Jenkins 共享库准备一个本地 Git 仓库。vars/ 目录非常特殊：其中的每个 .groovy 文件都会成为一个同名的流水线步骤。

运行以下命令，在 Jenkins 容器内创建 vars/sayHello.groovy：

docker exec jenkins bash -lc '
set -e
rm -rf /var/jenkins_home/shared-lib-src /var/jenkins_home/shared-lib.git
mkdir -p /var/jenkins_home/shared-lib-src/vars
cd /var/jenkins_home/shared-lib-src
git init -b main
git config user.email "jenkins@example.com"
git config user.name "Jenkins Shared Library"
cat > vars/sayHello.groovy <<'"'"'EOF'"'"'
def call(String name = "LabEx") {
    echo "Shared library says hello to ${name}"
}
EOF
git add vars/sayHello.groovy
git commit -m "Add sayHello shared library step"
'

现在，将该仓库发布为本地裸仓库（bare repository），并通过 git://localhost/shared-lib.git 对外提供服务：

docker exec jenkins bash -lc '
set -e
cd /var/jenkins_home/shared-lib-src
git init --bare --initial-branch=main /var/jenkins_home/shared-lib.git
git remote add origin /var/jenkins_home/shared-lib.git
git push origin main
touch /var/jenkins_home/shared-lib.git/git-daemon-export-ok
if [ -f /tmp/shared-lib-git-daemon.pid ]; then
  kill "$(cat /tmp/shared-lib-git-daemon.pid)" 2>/dev/null || true
  rm -f /tmp/shared-lib-git-daemon.pid
fi
git daemon --reuseaddr --base-path=/var/jenkins_home --export-all --detach --pid-file=/tmp/shared-lib-git-daemon.pid /var/jenkins_home
'

记录 Jenkins 将要使用的仓库分支：

docker exec jenkins git ls-remote git://localhost/shared-lib.git refs/heads/main | tee /home/labex/project/shared-library-repository.txt

输出应包含 refs/heads/main。

注册全局流水线库

在此步骤中，你将把该仓库注册为名为 labex-shared-lib 的 Jenkins 全局流水线库。流水线可以通过 @Library 加载此名称。

打开桌面界面。Firefox 会自动打开 Jenkins。如果未打开，请访问 http://localhost:8080。

在 Jenkins 仪表板中：

点击「Manage Jenkins」（管理 Jenkins），然后点击「System」（系统）。

滚动到「Global Trusted Pipeline Libraries」（全局受信任流水线库）或「Global Pipeline Libraries」（全局流水线库）。点击「Add」（添加）。

填写以下库信息：

Name（名称）：labex-shared-lib
Default version（默认版本）：main
勾选 Allow default version to be overridden（允许覆盖默认版本）
保持 Load implicitly（隐式加载）不勾选
Retrieval method（检索方法）：Modern SCM
Source Code Management（源代码管理）：Git
Project Repository（项目仓库）：git://localhost/shared-lib.git
Credentials（凭据）：- none -

点击「Save」（保存）。

Jenkins 全局流水线库配置

运行以下命令记录已保存的库配置：

docker exec jenkins sh -lc "grep -n -E '<name>labex-shared-lib</name>|git://localhost/shared-lib.git|<defaultVersion>main</defaultVersion>' /var/jenkins_home/org.jenkinsci.plugins.workflow.libs.GlobalLibraries.xml" | tee /home/labex/project/shared-library-config-lines.txt

创建加载库的流水线

在此步骤中，你将创建一个名为 shared-library-demo 的流水线任务。该流水线将加载 labex-shared-lib 并调用 vars/sayHello.groovy 中的自定义步骤 sayHello('LabEx')。

在 Jenkins 仪表板中：

点击「New Item」（新建任务），输入 shared-library-demo，选择「Pipeline」（流水线），然后点击「OK」。

滚动到「Pipeline」部分。保持 Definition 为 Pipeline script。

输入以下脚本：

@Library('labex-shared-lib@main') _

node {
    stage('Use Library') {
        sayHello('LabEx')
    }
}

点击「Save」（保存）。

使用共享库的 Jenkins 流水线

运行以下命令记录已保存的流水线脚本：

docker exec jenkins sh -lc "grep -n -E '@Library|sayHello' /var/jenkins_home/jobs/shared-library-demo/config.xml" | tee /home/labex/project/shared-library-job-config.txt

运行共享库流水线

在此步骤中，你将运行该流水线任务。Jenkins 将从本地 Git 仓库获取共享库，加载 vars/sayHello.groovy，并执行自定义步骤。

在 shared-library-demo 任务页面，点击「Build Now」（立即构建）。

当构建 #1 出现在构建历史中时，等待其完成。构建成功意味着 Jenkins 已成功加载库并运行了流水线脚本。

Jenkins 共享库构建结果

运行以下命令保存构建结果：

curl -fsS http://localhost:8080/job/shared-library-demo/1/api/json | tr ',' '\n' | grep '"result":"SUCCESS"' | tee /home/labex/project/shared-library-build-result.txt

检查共享库输出

在此步骤中，你将检查 Jenkins 控制台输出。关键证据是由 sayHello.groovy 打印的那一行。

打开构建 #1，然后点击「Console Output」（控制台输出）。

控制台应显示 Jenkins 加载了 labex-shared-lib 并打印了以下内容：

Shared library says hello to LabEx

Jenkins 共享库控制台输出

运行以下命令保存相同的控制台证据：

curl -fsS http://localhost:8080/job/shared-library-demo/1/consoleText | grep 'Shared library says hello to LabEx' | tee /home/labex/project/shared-library-console-lines.txt

总结

你准备了一个 Jenkins 共享库仓库，从仪表板将其注册为全局流水线库，创建了一个加载该库的流水线任务，并验证了自定义的 vars/ 步骤已在 Jenkins 控制台输出中成功运行。