Jenkins 实现 Gitlab API 调用及共享库应用

Author：rab
Gitlab 版本：15.1.2
Jenkins 版本：2.332.3

Jenkins 官方文档
Gitlab 官方文档

---

---

我们可通过 Branches API 接口来创建分支，先进行接口调试，调试完成后以 Jenkins Pipeline 的方式执行，并最终通过进一步优化实现 Jenkins 共享库构建效果。

一、Branches API

1.1 获取接口地址

此时，就可以根据官方接口文档，获取如下创建分支的接口地址。

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/branches?branch=newbranch&ref=main"

1.2 创建 Token

然后在 Gitlab 上创建 Token，操作步骤如下图：

创建完成后会生成一个 Token，复制到接口地址

curl --request POST --header "PRIVATE-TOKEN: DxVUpBnVmg4NUNfBdyxx" "https://192.168.56.133/api/v4/projects/5/repository/branches?branch=newbranch&ref=main"

# 这个toke与上图不符，是因为上图的toke被我删了，然后这是我重新创建的token

• 接口地址中 /projects/5 就是 Gitlab 的项目 ID，如果你要对下图项目做相关操作，应修改为 /projects/3；
• newbranch 表示你要创建的分支名称（自定义）；
• main 表示你以哪个分支为基础来创建新分支。

所以最终地址为：

curl --request POST --header "PRIVATE-TOKEN: DxVUpBnVmg4NUNfBdyxx" "https://192.168.56.133/api/v4/projects/3/repository/branches?branch=rab_test&ref=main"

# 我定义了一个名为rab_test的新分支，且以main分支为基础进行创建
# 如果你的Gitlab没有开启443认证，那需要把https--->http
# curl --request POST --header "PRIVATE-TOKEN: DxVUpBnVmg4NUNfBdyxx" "http://192.168.56.133/api/v4/projects/3/repository/branches?branch=rab_test&ref=main"

1.3 接口调试

1.3.1 shell 终端调试

此时，你在任意 shell 终端进行调试，最终看是否生成预期分支，这里我就在 Jenkins 服务器上执行上述接口地址。

看样子是没什么问题，然后到 Gitlab 上看看有没有创建指定的分支。

看到上图结果，完全是没问题的，说明调试已经调通了。

1.3.2 Postman 调试

1、新建 POST 请求

2、请求头添加 Token 信息（k-v）

3、配置好后点击 Send

4、Gitlab 查看结果

也是能够成功构建的。

postman 有一个好处就是，可以根据你的接口地址生成对应的语言片段，入下图，生成 cURL 格式的片段：

当然，它还支持其他语言片段，如 python、Java等

1.4 Pipeline 实现

以上接口都调通后，接下来就可以通过 Jenkins 流水线来实现了，写一个简单的案例，创建分支rab_test-2。

pipeline {
	agent any
	stages {
		stage("create branch"){
			steps{
				// 复制刚刚postman调通的接口地址
				sh """
					curl --location --request POST \
					"http://192.168.56.133/api/v4/projects/3/repository/branches?branch=rab_test-2&ref=main" \
					--header "PRIVATE-TOKEN: DxVUpBnVmg4NUNfBdyxx"
				"""
			}
		}
	}
}

进行 Jenkins 构建操作，如图构建成功。

接下来去 Gitlab 上看看是否生成新的分支。

完全没问题，由于我的分支在 Pipeline 脚本中写死了，后面你可以自己优化一下，比如传递一些参数进行动态创建。

二、优化 Pipeline

你会发现，上面的 Pipeline 脚本的接口都是写死的，也就是说如果你想修改相关参数值的话，需要进入脚本中修改，比较麻烦，因此我们再次进行优化。

2.1 参数化构建

实现功能：使用者可以灵活自定义新分支名、基础分支，而不需要再次进入修改 Pipeline 脚本，只需要传递参数即可值。

1、配置参数化配置

最终效果如下图：

2、修改 Pipeline 脚本

上述参数定义好后，接下来就需要把参数名写进 Pipeline 脚本对应位置，实现参数传递。

pipeline {
	agent any
	stages {
		stage("create branch"){
			steps{
				// 复制刚刚postman调通的接口地址
				sh """
					curl --location --request POST \
					"http://192.168.56.133/api/v4/projects/3/repository/branches?branch=${env.NewBranchName}&ref=${env.BaseBranchName}" \
					--header "PRIVATE-TOKEN: DxVUpBnVmg4NUNfBdyxx"
				"""
			}
		}
	}
}

3、构建验证

• Jenkins 构建

  

• Gitlab 查看是否创建成功

  

2.2 Token 加密

上面的 Token 是以明文形式传输传输的，并不安全，我们需要用到凭证方式来代替明文方式。

1、在安全设置中找到管理凭据

2、具体配置

3、通过 Jenkins 自带的片段生成器来生成相关片段语句

4、修改 Pipeline 脚本

pipeline {
	agent any
	stages {
		stage("Create Branch"){
			steps{
				script{
					withCredentials([string(credentialsId: 'gitlab-create-branch', variable: 'Gitlab_Token')]) {
						// 创建分支
						sh """
							curl --location --request POST \
							"http://192.168.56.133/api/v4/projects/3/repository/branches?branch=${env.NewBranchName}&ref=${env.BaseBranchName}" \
							--header "PRIVATE-TOKEN: ${Gitlab_Token}"
						"""
					}
				}
			}
		}
	}
}

5、构建验证

• Jenkins 构建

  

• Gitlab 查看是否创建成功

  

2.3 定义函数（方法）

函数的作用在于更加灵活的传递参数、减少书写代码量。

1、定义函数

注意：函数体的参数名要和定义函数中的参数保持一致

// 创建分支
def CreateBranch(ProjectID, NewBranchName, BaseBranchName) {
	withCredentials([string(credentialsId: 'gitlab-create-branch', variable: 'Gitlab_Token')]) {
		sh """
			curl --location --request POST \
			"http://192.168.56.133/api/v4/projects/${ProjectID}/repository/branches?branch=${NewBranchName}&ref=${BaseBranchName}" \
			--header "PRIVATE-TOKEN: ${Gitlab_Token}"
		"""
	}
}

// 流水线（主）
pipeline {
	agent any
	stages {
		stage("Create Branch") {
			steps {
				script {
					ProjectID = 3
					// 调用函数时，如果定义的参数类型为字符串时需夹双引号，为数字时则不需要
					CreateBranch(ProjectID, "${env.NewBranchName}", "${BaseBranchName}")
				}
			}
		}
	}
}

2、构建验证

• Jenkins 构建

  

• Gitlab 查看是否创建成功

  

到这里，Gitlab 的工程 ID 还是被写死的，因此我们需要通过 Gitlab 的项目名动态获取 Gitlab 项目对应的 ID 值，这也需要调用 Gitlab 的相关接口，如下图。

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?search=test"

# 参数说明
# PRIVATE-TOKEN：Token值
# test：表示你要填入的项目名称

# 修改一下
curl --header "PRIVATE-TOKEN: DxVUpBnVmg4NUNfBdyxx" "http://192.168.56.133/api/v4/projects?search=Tq"

现在命令行测试一下，看看该接口返回的结果；

可看到，已经返回了 Gitlab 中 Tq 项目的 id 值了，说明该接口可用。

Postman 上更直观一点

3、再次优化

// 请求地址
def HttpReq(ApiUrl, Method) {
	GitlabAPI = "http://192.168.56.133/api/v4"
	withCredentials([string(credentialsId: 'gitlab-create-branch', variable: 'Gitlab_Token')]) {
		response = sh returnStdout: true, script: """
			curl --location --request ${Method} \
				"${GitlabAPI}/${ApiUrl}" \
				--header "PRIVATE-TOKEN: ${Gitlab_Token}"
		"""
	}
	return response
}

// 创建分支
def CreateBranch(ProjectID, NewBranchName, BaseBranchName) {
	ApiUrl = "projects/${ProjectID}/repository/branches?branch=${NewBranchName}&ref=${BaseBranchName}"
	Method = "POST"
	HttpReq(ApiUrl, Method)
}

// 获取项目ID
def GetProjectID(ProjectName) {
	ApiUrl = "projects?search=${ProjectName}"
	Method = "GET"
	result = HttpReq(ApiUrl, Method)
	result = readJSON text: result
	return result[0]["id"]
}

// 流水线（主）
pipeline {
	agent any
	stages {
		stage("Create Branch") {
			steps {
				script {
					ProjectID = GetProjectID("${ProjectName}")
					CreateBranch(ProjectID, "${env.NewBranchName}", "${BaseBranchName}")
				}
			}
		}
	}
}

• 进行构建

  

• Gitlab 上查看是否生成

  

注意：如果你使用了 readJSON JSON 解析，那你需要安装如下插件，否则报错。

错误现象：提示没有 readJDSON 这个方法，这种报错类型一般是缺少插件导致的，安装对应插件即可。

三、共享库

上面已经做了相关优化了，但是在生产环境中的代码量远比上面多，而且定义的函数也会越来越多，因此，我们就需要使用 Jenkins 的共享库，共享库的作用是将具备同样性质或很少改动的函数（方法）归档于 Git 仓库管理，并在 Jenkinsfile 中调用（引用）的手段，这将大大减少 Pipeline 代码量。

3.1 创建共享库

1、创建项目仓库

2、添加目录/文件

• 点击 Web IDE

• 创建目录

  

• 添加文件

  

  

3、将定义好的方法提交到代码仓库

3.2 加载共享库

1、流水线脚本加载共享库

// 加载共享库，其中jenkinslib要与Jenkins系统配置中保持一致（jenkinslib可自定义），@amin表示共享库所在分支
@Library("jenkinslib@main") _
// 导入jenkinsfile.groovy。这里要注意：下面的jenkinsfile()名字必须与你共享库中jenkinsfile.groovy名一致，否则报错
def myjenkinsfile = new org.devops.jenkinsfile()

// 流水线（主）
pipeline {
	agent any
	tools {
		git 'git'
	}
	stages {
		stage("Create Branch") {
			steps {
				script {
					// 然后就可以调用共享库中的方法了 myjenkinsfile 即为我上面引用的方法（可在上面自定义）
					ProjectID = myjenkinsfile.GetProjectID("${env.ProjectName}")
					myjenkinsfile.CreateBranch(ProjectID, "${env.NewBranchName}", "${env.BaseBranchName}")
				}
			}
		}
	}
}

2、同样将流水线脚本也进行 Git 版本管理

这样的话便于管理 Jenkinfile 及共享库

3.3 Jenkins 配置

1、Jenkins 流水线配置

因为我们的流水线脚本进行了 Git 版本管理，所以你可以在 Jenkins 流水线配置中配置 URL 即可。

2、Jenkins 系统配置

3.4 Jenkins 构建

以上都配置好之后，接下来就开始构建了。

1、Jenkins 构建

2、Gitlab 查看是否构建成功

至此，已实现 Jenkins 如何调用 Gitlab API 及 Jenkins 共享库的最终应用。

<点击跳转至开头>