4. GitHub Webhook 配置

GitHub Webhook 是连接代码仓库与 Jenkins 的“事件触发器”。当仓库发生指定事件（如代码推送、PR 操作）时，GitHub 会向配置的 Payload URL 发送 HTTP POST 请求，Jenkins 收到后即可触发对应的 Pipeline 任务。本节将详细拆解 Webhook 的配置要素与最佳实践。

4.1 Webhook 配置入口与核心参数

在 GitHub 仓库的 Settings → Webhooks → Add webhook 中创建新的 Webhook。配置界面包含三个核心区域：Payload URL、Secret 和事件类型选择。

4.2 Payload URL 设置与网络可达性

Payload URL 必须满足两个条件：

• 公网可达： GitHub 服务器需要能够通过 HTTP/HTTPS 访问该地址。如果 Jenkins 位于内网，需配置反向代理（如 Nginx）或使用隧道工具（如 ngrok）暴露服务。
• 路径正确： 默认路径为 /github-webhook/，对应 Jenkins 的 GitHub Plugin 端点。如果使用 Multibranch Pipeline 或 Organization Folder，路径保持不变。

# 示例：通过 Nginx 反向代理暴露 Jenkins Webhook
# nginx.conf 片段
location /github-webhook/ {
    proxy_pass http://127.0.0.1:8080/github-webhook/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

4.3 Secret 令牌配置与 HMAC 验证

Secret 是 Webhook 安全性的第一道防线。GitHub 使用 HMAC-SHA1 算法对请求体进行签名，并将签名放在 X-Hub-Signature 请求头中。Jenkins 端使用相同的 Secret 进行校验，确保请求确实来自 GitHub 且未被篡改。

配置步骤：

1. 在 GitHub Webhook 设置中生成或输入一个强随机字符串作为 Secret。
2. 在 Jenkins 的 Manage Jenkins → Configure System → GitHub → Advanced 中，为对应的 GitHub 服务器配置相同的 Secret。
3. 如果使用 Pipeline Multibranch 项目，可在项目配置的 Branch Sources → GitHub → Credentials 中关联包含 Secret 的凭证。

# 生成强随机 Secret 的示例命令（Linux/macOS）
openssl rand -hex 32
# 输出示例：a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b

4.4 事件类型选择策略

GitHub 支持数十种事件类型，但 CI/CD 场景下只需关注少数关键事件。过度订阅事件会增加 Jenkins 负载和网络流量。

推荐选择： 在 Let me select individual events 模式下，勾选 push 和 pull_request 即可覆盖 90% 的 CI/CD 触发场景。如需更精细控制，可额外勾选 release 和 issue_comment。

4.5 Webhook 事件触发流程（SVG）

下图展示了从 GitHub 事件发生到 Jenkins Pipeline 启动的完整链路：

4.6 多事件类型与分支过滤（SVG）

实际生产环境中，同一个仓库可能同时触发多个事件。下图展示了 Jenkins 如何根据事件类型和分支条件进行智能路由：

4.7 配置验证与排错

配置完成后，建议执行以下验证步骤：

• 发送测试请求： 在 GitHub Webhook 设置页面底部点击 Redeliver 重新发送最近一次事件，或点击 Test payload 发送模拟事件。
• 检查 Jenkins 日志： 查看 $JENKINS_HOME/logs/github-webhook.log 或 Jenkins 系统日志，确认是否有 Received GitHub webhook 记录。
• 验证签名： 如果 Secret 配置错误，日志中会出现 Invalid signature 或 No signature found 错误。
• 网络连通性： 使用 curl 从外部网络测试 Payload URL 是否可达。

# 使用 curl 模拟 GitHub Webhook 请求（测试用）
curl -X POST http://jenkins.example.com/github-webhook/ \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature: sha1=test_signature" \
  -H "X-GitHub-Event: push" \
  -d '{"ref":"refs/heads/main","repository":{"full_name":"org/repo"}}'