mcpField
G
gitlab-webhook

gitlab-webhook

github.com/grandcamel开发487 次安装40 周前更新
代码仓库

关于 gitlab-webhook

gitlab-webhook 是通过 glab api 管理 GitLab 项目和群组 Webhook 的技能，适用于配置外部通知与 CI/CD 回调。它涵盖事件筛选、测试及 Webhook 生命周期操作。

主要功能

  1. 01列出项目和群组 Webhook
  2. 02创建、更新及删除 Webhook
  3. 03按事件类型配置触发条件
  4. 04测试 Webhook 事件
  5. 05查看分页结果以审计配置

适用场景

  1. 01为 Slack 设置推送和合并请求通知
  2. 02配置外部 CI 触发回调
  3. 03筛查项目现有 Webhook
  4. 04迁移 Webhook 地址并测试

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/grandcamel/gitlab-assistant-skills --skill gitlab-webhook

安装后在 Claude Code 中输入/gitlab-webhook确认已加载。

详细介绍

Webhook 技能

使用 glab api 原始端点调用管理 GitLab Webhook。

快速参考

操作命令模式风险
列出 Webhookglab api projects/:id/hooks-
获取 Webhookglab api projects/:id/hooks/:hook_id-
创建 Webhookglab api projects/:id/hooks -X POST -f ...⚠️
更新 Webhookglab api projects/:id/hooks/:hook_id -X PUT -f ...⚠️
删除 Webhookglab api projects/:id/hooks/:hook_id -X DELETE⚠️⚠️
测试 Webhookglab api projects/:id/hooks/:hook_id/test/:trigger -X POST⚠️
列出群组 Hookglab api groups/:id/hooks-

风险说明：- 安全 | ⚠️ 注意 | ⚠️⚠️ 警告 | ⚠️⚠️⚠️ 危险

何时使用此技能

始终在以下情况使用：

  • 用户提到“webhook”“hook”或“web hook”
  • 用户想将 GitLab 与外部服务集成
  • 用户提到“通知”“回调”或“触发 URL”
  • 用户想设置 CI/CD 集成或 Slack 通知

以下情况切勿使用：

  • 用户想配置内置集成（使用项目设置）
  • 用户想管理 CI/CD 流水线（使用 gitlab-ci）
  • 用户想管理系统 Hook（需要管理员访问权限）

API 先决条件

所需令牌范围： api

权限：

  • 查看 Webhook：Maintainer+
  • 管理 Webhook：Maintainer+

Webhook 事件

事件标记描述
推送push_events代码推送到仓库
标签tag_push_events创建/删除标签
合并请求merge_requests_events创建/更新/合并 MR
议题issues_events创建/更新/关闭议题
评论note_events对 MR/议题/提交的评论
机密评论confidential_note_events机密评论
作业job_eventsCI 作业状态变更
流水线pipeline_events流水线状态变更
部署deployment_events部署状态变更
Wikiwiki_page_events创建/更新 Wiki 页面
发布releases_events创建发布版本

可用命令

列出 Webhook
# List project webhooks
glab api projects/123/hooks --method GET

# List with pagination
glab api projects/123/hooks --paginate

# List group webhooks (Premium)
glab api groups/456/hooks --method GET

# Using project path
glab api "projects/$(echo 'mygroup/myproject' | jq -Rr @uri)/hooks"
获取 Webhook 详情
# Get specific webhook
glab api projects/123/hooks/789 --method GET
创建 Webhook
# Basic webhook for push events
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=true

# Webhook for MR and pipeline events
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=false \
  -f merge_requests_events=true \
  -f pipeline_events=true

# Webhook with secret token
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=true \
  -f token="my-secret-token" \
  -f enable_ssl_verification=true

# Full-featured webhook
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=true \
  -f tag_push_events=true \
  -f merge_requests_events=true \
  -f issues_events=true \
  -f note_events=true \
  -f pipeline_events=true \
  -f job_events=true \
  -f token="secret" \
  -f enable_ssl_verification=true

# Webhook for specific branches only
glab api projects/123/hooks --method POST \
  -f url="https://example.com/webhook" \
  -f push_events=true \
  -f push_events_branch_filter="main"
更新 Webhook
# Update URL
glab api projects/123/hooks/789 --method PUT \
  -f url="https://new-url.com/webhook"

# Enable additional events
glab api projects/123/hooks/789 --method PUT \
  -f pipeline_events=true \
  -f job_events=true

# Disable event
glab api projects/123/hooks/789 --method PUT \
  -f push_events=false

# Update secret token
glab api projects/123/hooks/789 --method PUT \
  -f token="new-secret-token"

# Change SSL verification
glab api projects/123/hooks/789 --method PUT \
  -f enable_ssl_verification=false
删除 Webhook
# Delete webhook
glab api projects/123/hooks/789 --method DELETE
测试 Webhook
# Test push event
glab api projects/123/hooks/789/test/push_events --method POST

# Test MR event
glab api projects/123/hooks/789/test/merge_requests_events --method POST

# Test tag push event
glab api projects/123/hooks/789/test/tag_push_events --method POST

# Test note event
glab api projects/123/hooks/789/test/note_events --method POST

# Test issues event
glab api projects/123/hooks/789/test/issues_events --method POST

Webhook 配置选项

选项类型描述
urlstringWebhook 端点 URL（必填）
tokenstring用于验证的密钥令牌
push_eventsboolean在推送时触发
push_events_branch_filterstring推送事件的分支筛选条件
tag_push_eventsboolean在推送标签时触发
merge_requests_eventsboolean在 MR 事件时触发
issues_eventsboolean在议题事件时触发
confidential_issues_eventsboolean在机密议题事件时触发
note_eventsboolean在评论时触发
confidential_note_eventsboolean在机密评论时触发
pipeline_eventsboolean在流水线事件时触发
job_eventsboolean在作业事件时触发
deployment_eventsboolean在部署时触发
wiki_page_eventsboolean在 Wiki 变更时触发
releases_eventsboolean在发布时触发
enable_ssl_verificationboolean验证 SSL 证书

常见工作流

工作流 1：设置 Slack 通知
# Create webhook for Slack
glab api projects/123/hooks --method POST \
  -f url="https://hooks.slack.com/services/T00/B00/XXX" \
  -f push_events=true \
  -f merge_requests_events=true \
  -f pipeline_events=true \
  -f enable_ssl_verification=true
工作流 2：设置 CI 触发器
# Webhook to trigger external CI
glab api projects/123/hooks --method POST \
  -f url="https://ci.example.com/trigger" \
  -f push_events=true \
  -f tag_push_events=true \
  -f token="ci-trigger-token" \
  -f push_events_branch_filter="main"
工作流 3：审计所有 Webhook
# List all webhooks with details
glab api projects/123/hooks --paginate | \
  jq -r '.[] | "ID: \(.id)\n  URL: \(.url)\n  Events: push=\(.push_events), mr=\(.merge_requests_events), pipeline=\(.pipeline_events)\n  SSL: \(.enable_ssl_verification)\n"'
工作流 4：将 Webhook 迁移到新 URL
# 1. Get current webhook config
glab api projects/123/hooks/789 | jq

# 2. Update URL
glab api projects/123/hooks/789 --method PUT \
  -f url="https://new-service.example.com/webhook"

# 3. Test the webhook
glab api projects/123/hooks/789/test/push_events --method POST
工作流 5：设置部署通知
# Webhook for deployment events only
glab api projects/123/hooks --method POST \
  -f url="https://deploy-tracker.example.com/webhook" \
  -f push_events=false \
  -f deployment_events=true \
  -f token="deploy-secret"
工作流 6：禁用所有非必要事件
hook_id=789

# Keep only push and MR events
glab api projects/123/hooks/$hook_id --method PUT \
  -f push_events=true \
  -f merge_requests_events=true \
  -f tag_push_events=false \
  -f issues_events=false \
  -f note_events=false \
  -f job_events=false \
  -f pipeline_events=false

Webhook 负载

GitLab 会发送包含事件数据的 JSON 负载。主要字段：

推送事件负载
{
  "object_kind": "push",
  "ref": "refs/heads/main",
  "before": "abc123...",
  "after": "def456...",
  "commits": [...],
  "project": {...}
}
MR 事件负载
{
  "object_kind": "merge_request",
  "event_type": "merge_request",
  "object_attributes": {
    "iid": 1,
    "title": "...",
    "state": "opened",
    "action": "open"
  }
}

验证 Webhook

使用密钥令牌验证 Webhook 的真实性：

# In your webhook handler, verify the X-Gitlab-Token header
# matches the token you configured

故障排查

问题原因解决方案
Webhook 未触发未启用事件检查事件标志
403 Forbidden不是维护者需要 Maintainer 或更高角色
SSL 验证失败证书无效使用 enable_ssl_verification=false 或修复证书
Webhook URL 无法访问网络/防火墙问题确认 GitLab 可以访问该 URL
测试返回错误端点错误检查 Webhook 处理程序日志
请求过多Webhook 循环确认处理程序不会触发事件

最佳实践

  1. 使用 HTTPS：Webhook 始终使用安全 URL
  2. 设置密钥令牌：使用密钥令牌验证 Webhook
  3. 仅启用所需事件：减少无关通知和处理
  4. 妥善处理失败：GitLab 会重试投递失败的请求
  5. 监控 Webhook 状态：在 GitLab 界面中检查近期投递记录
  6. 使用分支筛选器：将推送事件限制在相关分支

相关文档

评论

支持 Markdown