16. 自动化触发:GitLab Webhooks + API 打通你的工具链
「GitLab」系列已发布: 00. GitLab 不只是代码托管:一套 DevOps 平台的 6 大核心能力 | 01. GitLab 怎么装最省心?Omnibus/Docker/K8s 三种姿势 | 02. 装完 GitLab 先配啥?管理员视角的初始化设置清单 | 03. GitLab 角色搞不清?Member/Maintainer/Owner 权限全解 | 04. 从零建好第一个 GitLab 项目:权限、变量、CI 配置入门 | 05. GitLab MR 代码审查:Code Review 最佳实践 | 06. CI/CD 到底是什么?GitLab 流水线架构从概念到实战 | 07. Runner 装不好?GitLab Runner 单机/分布式/高可用全攻略 | 08. .gitlab-ci.yml 怎么写?从 Hello World 到生产配置 | 09. 从 0 到 1:Go + React 项目的 GitLab CI/CD 实战部署 | 10. 构建太慢?GitLab 缓存与工件管理:加速构建省时间 | 11. 测试/预发/生产怎么管?GitLab 多环境部署与金丝雀发布 | 12. 安全左移:GitLab SAST/DAST 自动化扫描,漏洞提前拦截 | 13. 镜像仓库不用 Harbor?GitLab Container Registry 一站式管理 | 14. 私有包怎么存?GitLab Package Registry:Maven/PyPI/NPM 全覆盖 | 15. GitLab 挂了怎么办?高可用架构 + 备份恢复业务不中断 | 16. 自动化触发:GitLab Webhooks + API 打通你的工具链(本文) | 17. 文档自动发布:GitLab Pages 代码改文档同步更新
事件一发生就自动通知、自动执行。Webhooks 推送事件、API 拉取数据,把 GitLab 和你的一堆工具串成一条自动化链路。
前置条件
已掌握 CI/CD 基本概念(第 06 篇)和 Pipeline 构建(第 09 篇)。需要创建 Personal Access Token 用于 API 调用和 Webhook 验证。
一、Webhooks
Webhook 是 GitLab 向外部服务发 HTTP POST 的事件通知机制。事件发生 → GitLab 向配置的 URL 发 JSON 负载。
支持的事件:
| 事件类型 | 触发时机 |
|---|---|
| Push events | 代码推送 |
| Tag push events | 标签推送 |
| Merge request events | MR 创建/更新/合并/关闭 |
| Issue events | Issue 创建/更新/关闭 |
| Pipeline events | Pipeline 状态变更 |
| Job events | Job 状态变更 |
| Release events | Release 创建/更新/删除 |
| Wiki page events | Wiki 页面变更 |
| Deployment events | 部署状态变更 |
| Note events | 评论创建/更新 |
| Confidential note events | 机密评论 |
| Feature flag events | 功能开关变更 |
flowchart LR A[GitLab 事件] --> B{触发 Webhook} B --> C[Push Hook] B --> D[MR Hook] B --> E[Pipeline Hook] B --> F[Release Hook] C & D & E & F --> G[外部服务] G --> H[处理逻辑] H --> I[通知/集成]
1.1 接收端示例
# webhook_receiver.py
from flask import Flask, request, jsonify
import hmac
app = Flask(__name__)
WEBHOOK_SECRET = "your-secret-token"
def verify_signature():
signature = request.headers.get('X-Gitlab-Token')
if not signature:
return False
return hmac.compare_digest(signature, WEBHOOK_SECRET)
@app.route('/webhook', methods=['POST'])
def handle_webhook():
if not verify_signature():
return jsonify({'error': 'Invalid signature'}), 403
event_type = request.headers.get('X-Gitlab-Event')
payload = request.json
if event_type == 'Push Hook':
branch = payload['ref'].replace('refs/heads/', '')
author = payload['commits'][0]['author']['name']
message = payload['commits'][0]['message']
print(f"[Push] {author} 推送到 {branch}: {message}")
elif event_type == 'Merge Request Hook':
action = payload['object_attributes']['action']
if action == 'merge':
source = payload['object_attributes']['source_branch']
target = payload['object_attributes']['target_branch']
user = payload['user']['name']
print(f"[MR Merged] {user} 将 {source} 合并到 {target}")
elif event_type == 'Pipeline Hook':
status = payload['object_attributes']['status']
project = payload['project']['name']
pipeline_id = payload['object_attributes']['id']
print(f"[Pipeline] {project}#{pipeline_id}: {status}")
return jsonify({'status': 'ok'})
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000)
1.1.1 配置与测试
项目 → Settings → Webhooks:填 URL、Secret Token、选事件、SSL 验证。
# API 创建 Webhook
curl --request POST \
--header "PRIVATE-TOKEN: $TOKEN" \
"https://gitlab.example.com/api/v4/projects/$PROJECT_ID/hooks" \
--data "url=https://example.com/webhook" \
--data "push_events=true" \
--data "token=my-secret-token"
二、GitLab API
2.1 认证
# Personal Access Token(个人脚本)
curl --header "PRIVATE-TOKEN: glpat-..." \
"https://gitlab.example.com/api/v4/projects"
# OAuth 2.0(第三方应用)
curl --header "Authorization: Bearer ***" \
"https://gitlab.example.com/api/v4/user"
# CI Job Token(CI/CD 内)
curl --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
"${CI_API_V4_URL}/projects"
2.2 常用操作
# 列出项目
curl --header "PRIVATE-TOKEN: $TOKEN" \
"https://gitlab.example.com/api/v4/projects?per_page=100&page=1"
# 创建项目
curl --request POST \
--header "PRIVATE-TOKEN: $TOKEN" \
--header "Content-Type: application/json" \
"https://gitlab.example.com/api/v4/projects" \
--data '{"name":"my-new-project","namespace_id":42,"visibility":"private","initialize_with_readme":true}'
# 删除项目
curl --request DELETE \
--header "PRIVATE-TOKEN: $TOKEN" \
"https://gitlab.example.com/api/v4/projects/$PROJECT_ID"
# 创建 MR
curl --request POST \
--header "PRIVATE-TOKEN: $TOKEN" \
--header "Content-Type: application/json" \
"https://gitlab.example.com/api/v4/projects/$PROJECT_ID/merge_requests" \
--data '{"source_branch":"feature/new-api","target_branch":"main","title":"feat: 新增用户 API","assignee_id":15,"labels":"backend,feature"}'
# 合并 MR
curl --request PUT \
--header "PRIVATE-TOKEN: $TOKEN" \
"https://gitlab.example.com/api/v4/projects/$PROJECT_ID/merge_requests/$MR_IID/merge" \
--data '{"merge_commit_message":"feat: 新增用户 API","should_remove_source_branch":true}'
# 触发 Pipeline
curl --request POST \
--header "Content-Type: application/json" \
"https://gitlab.example.com/api/v4/projects/$PROJECT_ID/trigger/pipeline" \
--data '{"token":"<trigger-token>","ref":"main","variables":{"DEPLOY_VERSION":"v1.2.3"}}'
# 取消 Pipeline
curl --request POST \
--header "PRIVATE-TOKEN: $TOKEN" \
"https://gitlab.example.com/api/v4/projects/$PROJECT_ID/pipelines/$PIPELINE_ID/cancel"
三、企业集成
3.1 钉钉/企微通知
notify:
stage: .post
script:
- |
STATUS_TEXT=""
case "$CI_JOB_STATUS" in
"success") STATUS_TEXT="成功" ;;
"failed") STATUS_TEXT="失败" ;;
"canceled") STATUS_TEXT="已取消" ;;
esac
curl -X POST "$DINGTALK_WEBHOOK" \
-H "Content-Type: application/json" \
-d "{
\"msgtype\": \"markdown\",
\"markdown\": {
\"title\": \"$CI_PROJECT_NAME Pipeline $STATUS_TEXT\",
\"text\": \"### $CI_PROJECT_NAME\n\n-**状态**: $STATUS_TEXT\n-**分支**: $CI_COMMIT_REF_NAME\n-**提交**: $CI_COMMIT_SHORT_SHA\n-**详情**: [查看](https://$CI_PIPELINE_URL)\"
}
}"
3.2 Jira 联动
jira-integration:
stage: .post
script:
- |
JIRA_ISSUE=$(echo "$CI_COMMIT_MESSAGE" | grep -oP '[A-Z]+-\d+')
if [ -n "$JIRA_ISSUE" ]; then
curl --request PUT \
--header "Authorization: Basic $(echo -n "$JIRA_EMAIL:$JIRA_API_TOKEN" | base64)" \
--header "Content-Type: application/json" \
"https://your-domain.atlassian.net/rest/api/3/issue/$JIRA_ISSUE/comment" \
--data "{\"body\": \"部署完成\n- 分支: $CI_COMMIT_REF_NAME\n- Pipeline: $CI_PIPELINE_URL\"}"
fi
3.3 自动化 Release Notes
# auto_release.py
import requests, sys
GITLAB_URL = "https://gitlab.example.com"
TOKEN = sys.argv[1]
PROJECT_ID = sys.argv[2]
TO_TAG = sys.argv[3] if len(sys.argv) > 3 else "HEAD"
headers = {"PRIVATE-TOKEN": TOKEN}
resp = requests.get(
f"{GITLAB_URL}/api/v4/projects/{PROJECT_ID}/merge_requests",
headers=headers,
params={"state": "merged", "target_branch": "main", "per_page": 100}
)
features, fixes, chores = [], [], []
for mr in resp.json():
title = mr['title']
if title.startswith('feat'):
features.append(f"- {title.replace('feat:', '').strip()}")
elif title.startswith('fix'):
fixes.append(f"- {title.replace('fix:', '').strip()}")
else:
chores.append(f"- {title}")
print(f"""## {TO_TAG}
### 新功能
{chr(10).join(features) if features else '无'}
### 修复
{chr(10).join(fixes) if fixes else '无'}
### 其他
{chr(10).join(chores) if chores else '无'}
""")
3.4 速率限制
| 认证方式 | 限制 |
|---|---|
| 未认证 | 60 req/min |
| Personal Access Token | 2000 req/min |
| CI Job Token | 2000 req/min |
| OAuth | 2000 req/min |
import time, requests
def api_call_with_retry(url, headers, max_retries=3):
for attempt in range(max_retries):
resp = requests.get(url, headers=headers)
if resp.status_code == 429:
retry_after = int(resp.headers.get('Retry-After', 60)
time.sleep(retry_after)
continue
return resp
raise Exception("Max retries exceeded")
四、Webhook 与 API 关系
sequenceDiagram participant Dev as 开发者 participant GitLab as GitLab participant Webhook as Webhook participant API as API Dev->>GitLab: push 代码 GitLab->>Webhook: 触发事件 Webhook->>外部服务: HTTP POST Dev->>API: 查询项目 API->>GitLab: 获取数据 GitLab-->>API: 返回 JSON
五、文章引用
📌 本文首发于微信公众号 【运维知识点滴】——专注运维实战干货,微信搜索“运维知识点滴”或扫下方二维码关注,更新不迷路。
| 微信公众号【运维知识点滴】 | 微信小程序【A5单据合并&大试卷拆分转A4打印】 |
|---|---|
![]() |
![]() |
| 运维实战干货 · 关注追更 | Word 转 PDF · 试卷/发票打印神器 · 免费 |
💡 小程序【A5单据合并&大试卷拆分转A4打印】是干嘛的? 一个 Word 转 PDF 的打印神器,专治“文档版式和打印机对不上”:
- A3 试卷打不出来? 学校发的电子版试卷多是 A3,家用打印机只吃 A4——上传 Word 一键转换:可缩到一页 A4(页数不变),也可对半拆成两张 A4(1:1 原大、字更清晰),两种模式自选;
- 版式不乱:真实渲染引擎原样转换、绝不重排内容,转出的 PDF 和原 Word 排版一致,公式/表格/图片不跑版;
- 两张 A5 单据拼一张 A4:出租车票、火车票等报销凭证拼版后,一次打印、整齐粘贴;
- 隐私省心:无需注册,转换结果留存 5 天、最多下载 5 次即自动删除,不留任何历史记录;
- 微信扫码即用,免费、免安装,支持 doc / docx(≤50MB)。
上一篇:15. GitLab 挂了怎么办?高可用架构 + 备份恢复业务不中断 | 下一篇:17. 文档自动发布:GitLab Pages 代码改文档同步更新

