Ubuntu 上 GitLab Webhooks 设置指南
一 前置准备
- 确保 GitLab 已安装并运行在 Ubuntu（自托管实例或 GitLab.com 均可）。
- 准备一个可被公网或内网访问的 Webhook 接收端点 URL（如内网服务需可达 GitLab；公网服务注意安全与限流）。
- 若使用 HTTPS，准备有效证书；如使用自签名证书，可在测试阶段临时关闭 SSL 验证（生产不建议）。
- 为提升安全性，准备一个 Secret Token（任意字符串），服务端将据此校验请求来源。
- 规划触发事件：常见有 Push events、Merge request events、Tag push events 等，按业务选择。
二 在 GitLab 项目中添加 Webhook
- 进入项目左侧 Settings > Webhooks。
- 在 URL 填写接收端地址；若 URL 含特殊字符需进行 百分号编码。
- 在 Secret token 填入你的密钥，用于请求签名校验。
- 在 Trigger 勾选需要的事件（如 Push events、Merge request events、Tag push events 等）。
- 保持 Enable SSL verification 勾选（生产环境推荐）；测试自签名证书时可临时取消勾选。
- 点击 Add webhook 保存。
三 在 Ubuntu 上接收并处理 Webhook
- 快速示例（Python Flask，接收并校验签名）
- 安装依赖：pip install flask python-dotenv
- 代码示例（.env 中设置 SECRET_TOKEN；仅校验 X-Gitlab-Token 头）：
- 运行服务：flask run --host 0.0.0.0 --port 5000
- 注意：该示例为演示，生产请加入签名算法校验、并发控制、重试幂等等
- 安全要点：
- 校验请求来源（如 Secret Token 或签名），拒绝非法请求
- 尽快返回 2xx，建议 < 1 秒；超时会导致 GitLab 判定失败并重试，可能产生重复事件
- 对输入做严格校验与过滤，避免命令注入等风险
- 对外暴露端口（如 80/443）需在防火墙放行，Nginx/Apache 反向代理可按需配置
- 接收端应稳定可靠，避免阻塞与长时间处理
- 常见集成
- Jenkins：安装 GitLab Plugin，在 Jenkins 保存 GitLab Personal Access Token，配置 GitLab 连接并测试；在 Pipeline 中使用 updateGitlabCommitStatus 将构建状态回写到 GitLab。
四 测试与排错
- 在 Webhooks 列表使用 Test 发送样例事件，查看是否收到请求与返回 2xx。
- 若失败，检查：
- URL 是否可达、端口是否开放（如 80/443）、防火墙/安全组策略
- Secret Token 是否一致、是否启用 SSL 验证（证书是否有效）
- 接收端是否快速返回有效 HTTP 响应；超时或异常会触发重试
- 事件是否被勾选、是否发送到正确的项目/分组
- 服务端日志与网络抓包，确认请求到达与头部/体内容
- 进阶：如需统一监听多个项目事件，可使用 Group webhooks（PREMIUM）；注意 GitLab.com 对 Webhook 的数量、大小与调用频率有限制。
