Jenkins 新项目接入指南 (基于 Generic Webhook Trigger)

Jenkins 新项目接入指南 (基于 Generic Webhook Trigger)

本文档用于指导如何在现有的 Jenkins 环境中接入一个新的 Git 项目。

📋 核心原理

所有项目共用同一个 Webhook URL，Jenkins 接收到请求后，会根据脚本中的 正则过滤规则 (regexpFilterExpression) 来判断当前的请求属于哪个项目，从而决定是否触发构建。

步骤 1：Jenkins 新建任务

1. 登录 Jenkins。
2. 点击左侧 "新建任务" (New Item) 。
3. 输入 任务名称 (建议与 Git 仓库名一致)。
4. 选择 "Pipeline" (流水线) 类型。
5. 点击 "确定" (OK) 。

步骤 2：配置 Pipeline 脚本 (核心步骤)

在任务配置页面的 Pipeline 部分，粘贴以下脚本模板，并修改 3 个关键位置。

✏️ 脚本模板 (请复制以下代码)

// 使用 properties 定义触发器
properties([
    pipelineTriggers([
        GenericTrigger(
            // 【固定配置】Token 保持不变，所有项目共用一个
            token: 'weixin-secret-token-2025', 
            causeString: 'Triggered by WeChat Git',
            printPostContent: true,
            silentResponse: false,
            genericVariables: [
                [key: 'repo_name', value: '$.repository.name'], 
                [key: 'branch', value: '$.ref'],
                [key: 'pusher_name', value: '$.user_name']
            ],
            
            // 构造检查字符串： "仓库名 分支名"
            regexpFilterText: '$repo_name $branch',
            
            // 🔴【修改点 1】项目过滤规则
            // 语法：^仓库名 refs/heads/分支名$
            // 示例：如果新项目叫 my-api，只监听 main 分支
            regexpFilterExpression: '^my-api refs/heads/main$'
        )
    ])
])

node {
    try {
        stage('Debug Info') {
            echo "✅ [新项目] 脚本启动"
            echo "📦 仓库: ${env.repo_name}"
            echo "🌿 分支: ${env.branch}"
        }

        stage('Checkout Code') {
            // 自动处理分支名
            def branchName = env.branch ? env.branch.replace('refs/heads/', '') : 'main'
            echo "🔄 检出分支: ${branchName}"

            cleanWs()

            checkout([
                $class: 'GitSCM', 
                branches: [[name: "*/${branchName}"]], 
                userRemoteConfigs: [[
                    // 【固定配置】凭据 ID 复用之前的配置，不用改
                    credentialsId: 'weixin-git-credentials-fixed', 
                    
                    // 🔴【修改点 2】新项目的 Git 地址
                    // 必须是 SSH 格式 (git@...)
                    url: 'git@git.weixin.qq.com:codeli/YOUR_NEW_PROJECT.git'
                ]]
            ])
        }

        stage('Build Project') {
            echo "🚀 开始构建..."
            // 🔴【修改点 3】构建命令
            // 在这里写新项目需要的构建脚本
            sh 'ls -al' 
            // sh 'npm install && npm run build'
        }

    } catch (e) {
        currentBuild.result = 'FAILURE'
        echo "❌ 构建失败: ${e.toString()}"
        throw e
    }
}

🔍 详细修改说明

1. 修改过滤规则 (regexpFilterExpression)

这是防止项目互相干扰的关键。

• 格式：^<仓库名> refs/heads/<分支名>$

• 示例：

  • 只触发 main 分支：^new-project refs/heads/main$
  • 触发 main 和 dev：^new-project refs/heads/(main|dev)$

2. 修改 Git 地址 (url)

• 找到 userRemoteConfigs 下的 url 字段。
• 将其改为新项目的 SSH 地址（以 git@ 开头）。

3. 修改构建命令

• 在 stage('Build Project') 中，将 sh 'ls -al' 替换为你实际的编译/部署命令。

步骤 3：配置 Git 仓库 Webhook

进入 新项目的 Git 网页端 (git.weixin.qq.com)，找到 设置 -> Webhooks。

• URL: http://<你服务器的ip地址>:8080/generic-webhook-trigger/invoke?token=weixin-secret-token-2025

  • (注意：Token 必须与脚本中的 token 保持一致)

• Secret Token: (留空即可，因为 token 已经在 URL 里了)

• Trigger: 勾选 Push events。

• SSL verification: 根据情况勾选（通常默认即可）。

• 点击 Add Webhook。

步骤 4：⚠️ 首次运行必须手动触发！

这是一个新手最容易忽略的步骤。

1. 保存完 Jenkins 任务配置后，必须手动点击一次左侧的 "Build Now" (立即构建) 。
2. 原因：Jenkins 只有在完整运行一次脚本后，才能读取并加载 properties([...]) 中的触发器配置。
3. 首次手动构建成功后，Webhook 自动触发功能才会生效。

常见问题排查

• Q: 手动构建成功，但 Push 代码不触发？

  • A: 检查 regexpFilterExpression 里的仓库名是否和 Git 上显示的完全一致（区分大小写）。

• Q: 报错 Permission denied？

  • A: 确认新项目是否也在 codeli 账号下。如果是其他账号的项目，需要去 Jenkins 凭据管理里添加新的 SSH 私钥，并修改脚本中的 credentialsId。