job pipeline如何使用token 触发-智慧文博士

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