GitLab等私有仓库通过Webhook推送代码后，Jenkins借助Generic Webhook Trigger插件接收HTTP请求并校验token，自动触发Pipeline构建，全程无需轮询，实时可靠。
在 Linux 环境下，通过 Webhook 实现私有 Git 仓库（如 Gitea、GitLab Self-Managed、Gogs 或自建 Git 服务）推送代码后自动触发 Jenkins 流水线，核心是：让 Git 服务在 push 事件发生时，向 Jenkins 发送一个 HTTP 请求；Jenkins 接收并验证该请求后，触发对应 Pipeline。整个过程不依赖轮询，实时性强，配置得当即可稳定运行。
确保 Jenkins 开启并配置好 Webhook 支持
Jenkins 默认不直接暴露 Webhook 接口，需借助插件实现安全接收。推荐使用官方维护的 Generic Webhook Trigger 插件（兼容性强，支持任意 Git 服务）或对应平台插件（如 GitLab Plugin、Gitea Plugin）。
- 进入 Jenkins → Manage Jenkins → Plugin Manager → Available，搜索并安装 Generic Webhook Trigger
- 重启 Jenkins（若提示需要）
- 新建或编辑一个 Pipeline 项目，在配置页向下滚动到 Build Triggers 区域
- 勾选 Generic Webhook Trigger，点击 Add token 设置一个唯一 secret token（例如
abc123xyz），用于后续 Git 服务端校验 - 在 Post content parameters 中可添加变量提取规则（如从 payload 提取
repository.name、ref），便于后续脚本判断分支或仓库
在私有 Git 服务中配置 Webhook（以 Gitea 为例）
Gitea、GitLab CE、Gogs 的 Webhook 配置界面相似，关键是要把 Jenkins 的接收地址和 token 正确填入。
- 进入你的仓库 → Settings → Webhooks → Add Webhook
-
Payload URL 填写 Jenkins 的 Webhook 地址，格式为：
http://your-jenkins-ip:8080/generic-webhook-trigger/invoke?token=abc123xyz -
Content type 选
application/json - 勾选触发事件，至少选择 Push Events；如需 PR 触发，再勾选 Pull Request Events
- （可选但推荐）启用 Secret：填写与 Jenkins 中一致的 token（如
abc123xyz），Gitea 会在请求头中带上X-Gitea-Signature，Jenkins 插件会自动校验 - 点击 Add Webhook 并测试发送（用 Test Delivery 查看 Jenkins 是否返回 200）
编写 Jenkinsfile 实现分支/条件识别与构建逻辑
Webhook 触发后，Jenkins 需知道该构建哪个分支、是否跳过某些场景（如文档提交）。可在 Jenkinsfile 中用 params 或环境变量提取信息。
- 在 Jenkins 项目配置中，Generic Webhook Trigger 区域添加参数映射，例如：
• Name:branch，JSON Path:$.ref（Gitea/GitLab 的 ref 是refs/heads/main）
• Name:repoName，JSON Path:$.repository.name - 在
Jenkinsfile中使用：pipeline { agent any parameters { string(name: 'branch', defaultValue: 'refs/heads/main', description: 'Git branch ref') } stages { stage('Checkout') { steps { script { // 提取真实分支名（去掉 refs/heads/） env.REAL_BRANCH = params.branch.replaceFirst('refs/heads/', '') } checkout([ $class: 'GitSCM', branches: [[name: "origin/${env.REAL_BRANCH}"]], extensions: [], userRemoteConfigs: [[url: 'http://your-gitea/internal/repo.git']] ]) } } stage('Build') { steps { sh 'make build' } } } }
调试与权限注意事项
常见失败原因集中在网络连通性、认证和 payload 解析上，建议按顺序排查：
-
Jenkins 能否被 Git 服务访问？ 检查防火墙（
ufw status）、SELinux（getenforce）、Jenkins 是否监听在 0.0.0.0（而非 localhost） -
Webhook 请求是否到达 Jenkins？ 查看 Jenkins 日志：
tail -f /var/log/jenkins/jenkins.log，触发后搜GenericTrigger或invoke - Token 不匹配或签名失败？ 确保 Gitea/GitLab 设置的 Secret 和 Jenkins 中 token 完全一致（区分大小写、无空格）
-
Jenkinsfile 找不到或语法错误？ 建议先将 Jenkinsfile 放在默认分支根目录，用
Pipeline script from SCM方式加载，避免因 Webhook 触发时 Jenkinsfile 尚未拉取导致失败 - Git 拉取权限问题？ Jenkins 使用的 SSH Key 或账号必须对私有仓库有读权限；建议用 Deploy Key 或专用机器人账号
整个链路清晰稳定后，每次 git push 到指定分支，Jenkins 就会秒级响应并启动构建。不需要额外守护进程或定时任务，轻量又可靠。
