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 · 试卷/发票打印神器 · 免费
运维实战干货 · 关注追更 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 代码改文档同步更新