# Jenkins 自动触发构建配置手册
> 适用场景：代码推送到指定分支后自动触发 Jenkins 构建部署，无需手动操作。
---
## 目录
- [方式一：Generic Webhook Trigger + GitHub Actions（当前方案）](#方式一generic-webhook-trigger--github-actions当前方案)
- [方式二：GitHub Webhook 直连 Jenkins（免 GitHub Actions）](#方式二github-webhook-直连-jenkins免-github-actions)
- [方式三：Jenkins Multibranch Pipeline + GitHub Integration](#方式三jenkins-multibranch-pipeline--github-integration)
---
## 方式一：Generic Webhook Trigger + GitHub Actions（当前方案）
### 架构
```
GitHub (push to uat)
└─> GitHub Actions (self-hosted runner)
└─> curl POST → Jenkins Generic Webhook Trigger
└─> Jenkins Pipeline (build → deploy → notify)
```
### 前置条件
| 组件 | 要求 |
|------|------|
| Jenkins 插件 | [Generic Webhook Trigger](https://plugins.jenkins.io/generic-webhook-trigger/) |
| Jenkins 插件 | [Git Parameter](https://plugins.jenkins.io/git-parameter/) |
| Jenkins 插件 | [Build User Vars](https://plugins.jenkins.io/build-user-vars-plugin/) |
| GitHub Runner | self-hosted runner（标签 `ltp`） |
| 构建工具 | Maven 3 (`M3`)、JDK 17 (`jdk17`) |
| 凭据 | `SRE_LTP_TOKEN`（Jenkins Credentials） |
### Step 1：配置 Jenkins Pipeline
在 Jenkins Job 中使用 Declarative Pipeline，核心配置如下：
#### 1.1 触发器配置（triggers）
```groovy
triggers {
GenericTrigger(
genericVariables: [
[key: 'ref', value: '$.ref'] // 从 webhook payload 提取分支名
],
token: 'ltp-explore-project-uat', // 自定义 token，需与 GitHub Actions 中一致
regexpFilterText: '$ref',
regexpFilterExpression: 'refs/heads/uat' // 仅 uat 分支触发
)
}
```
**关键参数说明：**
| 参数 | 作用 | 示例 |
|------|------|------|
| `genericVariables` | 从 JSON payload 中提取变量 | `$.ref` 提取推送分支 |
| `token` | 触发认证 token，每个 Job 唯一 | `ltp-explore-project-uat` |
| `regexpFilterText` | 参与正则匹配的变量 | `$ref` |
| `regexpFilterExpression` | 正则表达式，匹配才触发 | `refs/heads/uat` |
#### 1.2 构建参数（parameters）
```groovy
parameters {
gitParameter(
name: 'BRANCH',
type: 'PT_BRANCH_TAG',
branchFilter: 'origin/(.*)',
defaultValue: 'origin/uat',
description: '选择要构建的分支/tag（不选择默认 origin/uat）',
selectedValue: 'DEFAULT',
sortMode: 'DESCENDING_SMART',
useRepository: '.*',
quickFilterEnabled: true,
listSize: '5'
)
choice(name: 'Deploy_Env', choices: ['uat'], description: '选择部署环境')
choice(name: 'start', choices: ['true','false'], description: '是否自动重启')
booleanParam(name: 'MAVEN_API_MODE', defaultValue: false, description: 'Build JAR Only')
}
```
#### 1.3 流水线阶段（stages）
```
Checkout → Build → Deploy
```
**Checkout 阶段：**
- 浅克隆（`depth: 1, shallow: true`）加速拉取
- 提取 Git 提交者、提交信息、Commit SHA
**Build 阶段：**
- 注入 `SRE_LTP_TOKEN` 凭据到 `settings.xml`
- 调用 `/data/maven_build-nonprod.sh` 执行 Maven 构建
- 支持 `MAVEN_API_MODE`：`true` 时仅构建 JAR，不部署
**Deploy 阶段：**
- `MAVEN_API_MODE=true`：跳过部署（SDK/API 模式）
- `MAVEN_API_MODE=false`：调用 `/data/java_deploy-nonprod.sh` 执行部署
- 支持 dev / qa / 默认环境分发
#### 1.4 构建通知（post）
```groovy
post {
success {
// 调用飞书通知脚本
sh "python3 /data/notify_lark.py <job> <build_number> <url> <author> <commit> <msg> <user> <env> <branch> success"
}
failure {
sh "python3 /data/notify_lark.py ... fail"
}
}
```
### Step 2：配置 GitHub Actions
在仓库 `.github/workflows/` 目录创建工作流文件：
```yaml
# .github/workflows/trigger-jenkins-uat.yml
name: Trigger Jenkins UAT
on:
push:
branches:
- uat
jobs:
trigger-jenkins:
name: Trigger Jenkins UAT Job
runs-on: [self-hosted, ltp]
steps:
- name: Trigger Jenkins
run: |
curl -X POST \
"https://jenkins.icbc.com/generic-webhook-trigger/invoke?token=ltp-explore-project-uat" \
-H "Content-Type: application/json" \
-d '{"ref": "refs/heads/uat"}'
```
### Step 3：新项目适配清单
为新项目配置时，需修改以下内容：
| 修改项 | 位置 | 说明 |
|--------|------|------|
| `token` | Jenkins Pipeline `triggers` 块 | 改为项目唯一 token，如 `ltp-<project>-uat` |
| `regexpFilterExpression` | Jenkins Pipeline `triggers` 块 | 按需修改触发分支 |
| `url` | Pipeline `Checkout` 阶段 | 改为目标仓库 Git 地址 |
| `defaultValue` | `gitParameter` | 改为默认分支 |
| `choices` | `Deploy_Env` | 按需添加部署环境 |
| `token` | GitHub Actions `curl` 命令 | 与 Jenkins 中的 token 保持一致 |
| `branches` | GitHub Actions `on.push` | 改为目标触发分支 |
---
## 方式二：GitHub Webhook 直连 Jenkins（免 GitHub Actions）
### 架构
```
GitHub (push event)
└─> GitHub Webhook (直接 POST)
└─> Jenkins Generic Webhook Trigger
└─> Jenkins Pipeline
```
### 优势
- 无需 self-hosted runner，减少基础设施维护
- 延迟更低（少一跳）
- 配置更简单
### 配置步骤
#### 2.1 Jenkins 侧（与方式一相同）
Pipeline 中的 `triggers` 块保持不变，确保 Generic Webhook Trigger 插件已安装。
#### 2.2 GitHub 仓库配置 Webhook
1. 进入仓库 **Settings → Webhooks → Add webhook**
2. 填写以下信息：
| 字段 | 值 |
|------|------|
| Payload URL | `https://jenkins.icbc.com/generic-webhook-trigger/invoke?token=ltp-explore-project-uat` |
| Content type | `application/json` |
| Secret | （可选）设置 HMAC 密钥验证请求来源 |
| Events | 选择 **Just the push event** |
| Active | 勾选 |
#### 2.3 分支过滤
分支过滤完全由 Jenkins 侧的 `regexpFilterExpression` 负责。GitHub Webhook 会在每次 push 时发送事件，Jenkins 收到后用正则匹配 `$.ref` 字段，不匹配则忽略。
#### 2.4 安全加固（推荐）
```groovy
triggers {
GenericTrigger(
genericVariables: [
[key: 'ref', value: '$.ref']
],
token: 'ltp-explore-project-uat',
tokenCredentialId: '', // 或使用 Jenkins Credential 存储 token
regexpFilterText: '$ref',
regexpFilterExpression: 'refs/heads/uat',
silentResponse: true // 不返回触发详情，防止信息泄露
)
}
```
如果配置了 Webhook Secret，需在 Jenkins 的 Generic Webhook Trigger 配置中启用 HMAC 验证：
```groovy
hmacKeyId: 'github-webhook-secret' // Jenkins Credentials ID
```
#### 2.5 验证
```bash
# 在 GitHub Webhook 页面点击 "Recent Deliveries" 查看投递结果
# 或手动测试：
curl -X POST \
"https://jenkins.icbc.com/generic-webhook-trigger/invoke?token=ltp-explore-project-uat" \
-H "Content-Type: application/json" \
-d '{"ref": "refs/heads/uat"}'
```
---
## 方式三：Jenkins Multibranch Pipeline + GitHub Integration
### 架构
```
GitHub (push / PR event)
└─> GitHub App / Webhook
└─> Jenkins GitHub Branch Source
└─> Multibranch Pipeline (自动发现分支)
└─> Jenkinsfile (per branch)
```
### 优势
- 自动发现新分支和 PR，无需为每个分支手动配置 Job
- 天然支持 PR 构建和状态回报
- 分支删除后自动清理 Job
- 更符合 GitOps 理念
### 前置条件
| 组件 | 要求 |
|------|------|
| Jenkins 插件 | [GitHub Branch Source](https://plugins.jenkins.io/github-branch-source/) |
| Jenkins 插件 | [Pipeline: Multibranch](https://plugins.jenkins.io/workflow-multibranch/) |
| GitHub | GitHub App 或 Personal Access Token |
### 配置步骤
#### 3.1 创建 GitHub App（推荐）或 PAT
**GitHub App 方式（推荐）：**
1. GitHub → Settings → Developer settings → GitHub Apps → New GitHub App
2. 权限：`Contents: Read`、`Metadata: Read`、`Commit statuses: Read & Write`
3. 生成 Private Key，下载 `.pem` 文件
4. 在 Jenkins 中添加 Credential：`Kind: GitHub App`
**PAT 方式（简单）：**
1. GitHub → Settings → Developer settings → Personal access tokens
2. 权限：`repo`（Full control）
3. 在 Jenkins 中添加 Credential：`Kind: Username with password`（用户名填 GitHub 用户名，密码填 PAT）
#### 3.2 创建 Multibranch Pipeline Job
1. Jenkins → New Item → **Multibranch Pipeline**
2. Branch Sources → Add source → **GitHub**
3. 配置：
| 字段 | 值 |
|------|------|
| Credentials | 选择上一步创建的凭据 |
| Repository HTTPS URL | `https://github.com/LiquidityTech/ltp-explore-project.git` |
| Behaviours | Discover branches: All branches |
| Build Configuration | Mode: by Jenkinsfile / Script Path: `Jenkinsfile` |
| Scan Multibranch Pipeline Triggers | Periodically if not otherwise run: 1 minute（兜底轮询） |
#### 3.3 仓库根目录放置 Jenkinsfile
```groovy
// Jenkinsfile（放在仓库根目录）
pipeline {
agent any
tools {
maven "M3"
jdk 'jdk17'
}
stages {
stage('Check Branch') {
steps {
script {
// 仅 uat 分支执行完整流程，其他分支仅构建
env.IS_UAT = (env.BRANCH_NAME == 'uat') ? 'true' : 'false'
echo "Branch: ${env.BRANCH_NAME}, IS_UAT: ${env.IS_UAT}"
}
}
}
stage('Build') {
steps {
script {
GIT_COMMIT = sh(script: 'git rev-parse HEAD', returnStdout: true).trim()
GIT_AUTHOR = sh(script: 'git log -1 --pretty=format:%an', returnStdout: true).trim()
GIT_MSG = sh(script: 'git log -1 --pretty=format:%s', returnStdout: true).trim()
withCredentials([string(credentialsId: 'SRE_LTP_TOKEN', variable: 'SRE_LTP_TOKEN')]) {
sh """
sed -i "s|SRE_LTP_TOKEN|\${SRE_LTP_TOKEN}|g" .github/workflows/settings.xml
GIT_COMMIT=${GIT_COMMIT} JOB_NAME=${env.JOB_BASE_NAME} sh /data/maven_build-nonprod.sh
"""
}
}
}
}
stage('Deploy') {
when {
environment name: 'IS_UAT', value: 'true'
}
steps {
script {
withEnv([
"GIT_COMMIT=${GIT_COMMIT}",
"JOB_NAME=${env.JOB_BASE_NAME}",
"Deploy_Env=uat",
"GIT_MSG=${GIT_MSG}",
"start=true"
]) {
sh "sh /data/java_deploy-nonprod.sh"
}
}
}
}
}
post {
success {
script {
if (env.IS_UAT == 'true') {
sh """
python3 /data/notify_lark.py \
"${env.JOB_NAME}" "${env.BUILD_NUMBER}" "${env.BUILD_URL}" \
"${GIT_AUTHOR}" "${GIT_COMMIT}" "${GIT_MSG}" "auto" "uat" "${env.BRANCH_NAME}" "success"
"""
}
}
}
failure {
script {
if (env.IS_UAT == 'true') {
sh """
python3 /data/notify_lark.py \
"${env.JOB_NAME}" "${env.BUILD_NUMBER}" "${env.BUILD_URL}" \
"${GIT_AUTHOR}" "${GIT_COMMIT}" "${GIT_MSG}" "auto" "uat" "${env.BRANCH_NAME}" "fail"
"""
}
}
}
}
}
```
#### 3.4 自动触发机制
Multibranch Pipeline 通过以下方式感知代码变更：
1. **GitHub Webhook（推荐）：** GitHub 推送事件通知 Jenkins 立即扫描
- Webhook URL: `https://jenkins.icbc.com/github-webhook/`
- Events: `push`, `pull_request`
2. **轮询兜底：** 配置 `Scan Multibranch Pipeline Triggers` 周期性扫描（建议 1-5 分钟）
---
## 方案对比
| 维度 | 方式一：GWT + GH Actions | 方式二：GWT + GitHub Webhook | 方式三：Multibranch Pipeline |
|------|--------------------------|-------------------------------|------------------------------|
| 复杂度 | 中等 | **最低** | 较高（初始配置） |
| 依赖 | self-hosted runner | 无额外依赖 | GitHub App/PAT |
| 分支管理 | 手动配置 token | 手动配置 token | **自动发现** |
| PR 构建 | 需额外配置 | 需额外配置 | **原生支持** |
| 延迟 | ~5-10s（经 GH Actions） | **~1-2s（直连）** | ~1-5s |
| 安全性 | Runner 网络隔离 | 需暴露 Jenkins 端点 | GitHub App 权限粒度细 |
| 适合场景 | 已有 GH Actions 基础设施 | 简单项目、快速接入 | 多分支开发、PR 驱动工作流 |
## 推荐选择
- **已有 self-hosted runner + 少量项目** → 方式一（当前方案）
- **快速接入 / 减少依赖** → 方式二（GitHub Webhook 直连）
- **多分支开发 / 需要 PR 构建 / 新项目** → 方式三（Multibranch Pipeline）Jenkins 自动触发构建配置手册
meijinmeng2026-04-10 17:44