Jenkins Pipeline 使用 Token 触发构建的完整指南
Jenkins Pipeline 支持多种通过 Token 触发构建的方式，主要包括 内置远程触发 和 Generic Webhook Trigger 插件 两种方式。下面详细介绍具体实现方法。
一、生成 Token
1. 用户 API Token（用于认证）
在 Jenkins 中生成用户 API Token，用于身份验证：
步骤：
-
登录 Jenkins → 点击右上角用户名 → 选择 "Configure"
-
找到 "API Token" 部分
-
点击 "Add new Token" → 输入 Token 名称 → 点击 "Generate"
-
务必保存好生成的 Token，只显示一次
2. Job 触发 Token（用于授权）
在 Job 配置中设置触发令牌：
步骤：
-
进入 Pipeline Job 配置页面
-
找到 "构建触发器" 部分
-
勾选 "Trigger builds remotely"
-
输入 "Authentication Token"（例如：
my-secret-token-123） -
保存配置
二、Pipeline 中配置 Token 触发
方式 1：Generic Webhook Trigger 插件（推荐）
安装插件：Generic Webhook Trigger Plugin
在 Jenkinsfile 中配置触发器：
groovy
复制
pipeline {
agent any
// 定义触发器
triggers {
GenericTrigger(
// 从 Webhook 请求中提取变量
genericVariables: [
[key: 'ref', value: '$.ref'],
[key: 'branch', value: '$.ref', expressionType: 'JSONPath'],
[key: 'commit', value: '$.after']
],
// 触发 Token，建议从 Jenkins 凭据中获取
token: 'jenkins-token-xxx',
// tokenCredentialId: 'webhook-token-credentials', // 从凭据中获取更安全
// 构建原因说明
causeString: 'Triggered on $ref',
// 打印调试信息
printContributedVariables: true,
printPostContent: true,
// 过滤触发条件
regexpFilterText: '$ref',
regexpFilterExpression: 'refs/heads/(main|develop)' // 只匹配 main 和 develop 分支
)
}
stages {
stage('Process Webhook') {
steps {
script {
// 使用从 Webhook 提取的变量
echo "Branch: ${env.branch}"
echo "Commit: ${env.commit}"
}
}
}
}
}
触发请求示例：
bash
复制
# 在 URL 中传递 token
curl -X POST \
-H "Content-Type: application/json" \
-d '{"ref": "refs/heads/main", "after": "abc123"}' \
http://jenkins.local:8080/generic-webhook-trigger/invoke?token=jenkins-token-xxx
方式 2：内置远程触发配置
Declarative Pipeline 示例
groovy
复制
pipeline {
agent any
// 配置 Job 属性，包括触发器
properties([
pipelineTriggers([
// 启用远程触发
triggers: [
[
$class: 'hudson.triggers.TimerTrigger',
spec: 'H/15 * * * *' // 定时触发，可选
]
]
])
])
parameters {
string(name: 'ENVIRONMENT', defaultValue: 'dev', description: '部署环境')
booleanParam(name: 'DEPLOY', defaultValue: false, description: '是否部署')
}
stages {
stage('Build') {
steps {
echo "Building for ${params.ENVIRONMENT}"
}
}
}
}
注意：内置远程触发在 Job 配置页面设置 Token 即可，Jenkinsfile 中无需额外配置。
三、触发构建的多种方式
1. 使用 curl 命令触发
无参数 Pipeline
bash
复制
# 使用 Job Token 触发（无需认证）
curl -X POST "http://JENKINS_URL/job/PIPELINE_JOB/build?token=my-secret-token-123"
# 使用 API Token 认证（更安全）
curl -X POST "http://JENKINS_URL/job/PIPELINE_JOB/build" \
--user "username:api-token"
带参数 Pipeline
bash
复制
# 使用 buildWithParameters
curl -X POST "http://JENKINS_URL/job/PIPELINE_JOB/buildWithParameters" \
--user "username:api-token" \
--data "token=my-secret-token-123" \
--data "ENVIRONMENT=production" \
--data "DEPLOY=true"
# 或使用 URL 参数（需设置"Build Authorization Token Root"插件）
curl -X POST "http://JENKINS_URL/job/PIPELINE_JOB/buildWithParameters?token=my-secret-token-123&ENVIRONMENT=production&DEPLOY=true"
2. 使用 Python 脚本触发
Python
复制
import requests
from requests.auth import HTTPBasicAuth
# Jenkins 配置
jenkins_url = "http://localhost:8080"
job_name = "my-pipeline"
username = "jenkins_user"
api_token = "11c343cd5f00421..." # 用户 API Token
job_token = "my-secret-token-123" # Job 触发 Token
# 构建 URL
url = f"{jenkins_url}/job/{job_name}/buildWithParameters"
# 参数
params = {
'token': job_token,
'ENVIRONMENT': 'staging',
'DEPLOY': 'true'
}
try:
response = requests.post(
url,
auth=HTTPBasicAuth(username, api_token),
data=params
)
if response.status_code == 201:
print("✅ 构建成功触发！")
print(f"构建队列位置: {response.headers.get('Location')}")
else:
print(f"❌ 构建失败：{response.status_code}")
print(response.text)
except Exception as e:
print(f"❌ 发生错误：{str(e)}")
3. 在另一个 Pipeline 中触发
groovy
复制
pipeline {
agent any
stages {
stage('Trigger Remote Job') {
steps {
script {
// 方式 1：使用 build 步骤
build(
job: '/folder/another-pipeline',
parameters: [
string(name: 'ENVIRONMENT', value: 'prod'),
booleanParam(name: 'DEPLOY', value: true)
],
wait: false // 是否等待远程 Job 完成
)
// 方式 2：使用 HTTP 请求
sh """
curl -X POST "http://jenkins:8080/job/another-pipeline/buildWithParameters" \
--user "user:api-token" \
--data "token=job-token" \
--data "ENVIRONMENT=prod"
"""
}
}
}
}
}
四、安全最佳实践
-
使用凭据管理 Token：
-
在 Jenkins 中创建 "Secret text" 类型的凭据存储 Token
-
在 Pipeline 中通过
credentials()函数引用
-
groovy
复制
pipeline {
agent any
triggers {
GenericTrigger(
tokenCredentialId: 'webhook-token-credentials', // 从凭据获取
// 其他配置...
)
}
}
-
限制 Token 权限：
-
为不同的集成创建独立的 Jenkins 用户
-
只授予最小必要权限
-
-
使用 HTTPS：
-
生产环境务必使用 HTTPS 协议
-
避免 Token 明文传输
-
-
IP 白名单：
-
在 Jenkins 中配置允许的源 IP 地址
-
防止未授权访问
-
五、完整示例：GitLab Webhook 触发
groovy
复制
pipeline {
agent any
triggers {
GenericTrigger(
genericVariables: [
[key: 'ref', value: '$.ref'],
[key: 'user', value: '$.user_username'],
[key: 'project', value: '$.project.name']
],
token: 'gitlab-integration-token',
causeString: '$user 触发了 $project 构建',
regexpFilterText: '$ref',
regexpFilterExpression: 'refs/heads/(main|develop|release/.*)'
)
}
environment {
// 使用提取的变量
BRANCH = env.ref?.replace('refs/heads/', '')
}
stages {
stage('Checkout') {
steps {
echo "检出分支: ${env.BRANCH}"
// 根据分支名检出代码
}
}
stage('Build') {
when {
anyOf {
branch 'main'
branch 'develop'
}
}
steps {
echo "构建项目 ${env.project}"
// 执行构建逻辑
}
}
}
post {
always {
echo "构建完成，触发者: ${env.user}"
}
}
}
GitLab Webhook 配置：
-
URL:
http://jenkins.example.com/generic-webhook-trigger/invoke?token=gitlab-integration-token -
Trigger:
Push events -
Secret Token:
gitlab-integration-token
六、常见问题排查
-
403 错误：检查用户权限和 CSRF Protection 设置
-
401 错误：API Token 或用户名错误
-
无法触发：检查 Token 是否匹配，正则过滤条件是否满足
-
参数缺失：确保 URL 使用
buildWithParameters而不是build
通过以上配置，你可以安全、灵活地使用 Token 触发 Jenkins Pipeline 构建，实现与 GitLab、GitHub、自定义脚本等系统的集成。
扫一扫
1641
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
