gitlink-cli/skills/gitlink-webhook/SKILL.md

name	version	description	metadata
gitlink-webhook	1.0.0	Webhook 管理：创建、查看、更新、删除、测试 Webhook，配置自动化触发器。当用户需要配置 GitLink 仓库的 Webhook 自动化通知时触发。	requires cliHelp bins gitlink-cli gitlink-cli webhook --help

gitlink-webhook（Webhook 操作）

CRITICAL — 开始前必须先阅读 ../gitlink-shared/SKILL.md，其中包含认证、权限处理和 API 注意事项。 CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。 CRITICAL — GitLink 操作只能用 gitlink-cli。禁止用 gh（GitHub CLI）操作 GitLink 资源。gh 仅适用于 GitHub 平台。

前置条件： 先阅读 ../gitlink-shared/SKILL.md 了解认证和全局参数。

Shortcuts

Shortcut	说明	需要认证
webhook +list	列出仓库的所有 Webhook	是
webhook +create	创建新 Webhook	是
webhook +update	更新 Webhook 配置	是
webhook +delete	删除 Webhook	是
webhook +test	测试 Webhook 推送（发送 ping 事件）	是
webhook +info	查看 Webhook 详情	是
webhook +events	列出所有支持的事件类型	否

支持的事件类型

事件类型	说明	触发时机
push	代码推送事件	向仓库推送代码时
pull_request	Pull 请求事件	创建、更新、关闭 PR 时
issue	Issue 事件	创建、更新、关闭 Issue 时
issue_assign	Issue 指派事件	Issue 被指派给用户时
issue_comment	Issue 评论事件	Issue 添加评论时
pull_request_assign	PR 指派事件	PR 被指派给审查者时
pull_request_comment	PR 评论事件	PR 添加评论时
merge_request	合并请求事件	PR 被合并时
repository	仓库事件	仓库设置变更时
branch	分支事件	创建或删除分支时
tag	标签事件	创建或删除标签时

使用示例

基本操作

# 列出仓库的所有 Webhook
gitlink-cli webhook +list --owner myuser --repo myrepo

# 查看 Webhook 详情
gitlink-cli webhook +info --owner myuser --repo myrepo --id 123

# 列出所有支持的事件类型
gitlink-cli webhook +events

创建 Webhook

# 创建基本的 Webhook（仅监听 push 事件）
gitlink-cli webhook +create --owner myuser --repo myrepo --url https://example.com/webhook

# 创建多事件 Webhook
gitlink-cli webhook +create --owner myuser --repo myrepo --url https://example.com/webhook --events push,pull_request,issue

# 创建带密钥的 Webhook
gitlink-cli webhook +create --owner myuser --repo myrepo --url https://example.com/webhook --secret my-secret-key --events push

# 创建带描述的 Webhook
gitlink-cli webhook +create --owner myuser --repo myrepo --url https://example.com/webhook --description "CI/CD automation"

更新 Webhook

# 更新 Webhook URL
gitlink-cli webhook +update --owner myuser --repo myrepo --id 123 --url https://new-url.com/webhook

# 更新监听事件
gitlink-cli webhook +update --owner myuser --repo myrepo --id 123 --events push,pull_request

# 激活/停用 Webhook
gitlink-cli webhook +update --owner myuser --repo myrepo --id 123 --active false

# 更新多个属性
gitlink-cli webhook +update --owner myuser --repo myrepo --id 123 --url https://new-url.com/webhook --events push,pull_request --secret new-secret

测试和删除

# 测试 Webhook（发送 ping 事件）
gitlink-cli webhook +test --owner myuser --repo myrepo --id 123

# 测试特定事件类型
gitlink-cli webhook +test --owner myuser --repo myrepo --id 123 --event push

# 删除 Webhook
gitlink-cli webhook +delete --owner myuser --repo myrepo --id 123

典型使用场景

场景1: 配置 CI/CD 自动化

# 为 CI/CD 系统创建 Webhook
gitlink-cli webhook +create \
  --owner myuser --repo myrepo \
  --url https://ci.example.com/gitlink/webhook \
  --events push,pull_request \
  --secret ci-secret-key \
  --description "Trigger CI/CD pipeline"

场景2: 配置 Issue 通知

# 创建 Issue 通知 Webhook
gitlink-cli webhook +create \
  --owner myuser --repo myrepo \
  --url https://notification.example.com/issues \
  --events issue,issue_comment,issue_assign \
  --description "Issue notifications"

场景3: 配置 PR 审查通知

# 创建 PR 审查 Webhook
gitlink-cli webhook +create \
  --owner myuser --repo myrepo \
  --url https://review.example.com/prs \
  --events pull_request,pull_request_comment,pull_request_assign \
  --description "PR review notifications"

错误处理

常见错误

1. 认证错误

Error: [401] Authentication failed

解决方案: 运行 gitlink-cli auth login 重新认证

2. 权限不足

Error: [403] You are not authorized to manage webhooks

解决方案: 确认您对仓库有管理员权限

3. 无效的事件类型

Error: no valid events specified

解决方案: 使用 gitlink-cli webhook +events 查看支持的事件类型

4. Webhook 不存在

Error: [404] Webhook not found

解决方案: 使用 gitlink-cli webhook +list 确认 Webhook ID 是否正确

AI Agent 使用指南

检查现有 Webhook

# 1. 列出所有 Webhook
gitlink-cli webhook +list --owner $OWNER --repo $REPO --format json

# 2. 检查是否有特定类型的 Webhook
gitlink-cli webhook +list --owner $OWNER --repo $REPO --format json | jq '.data.webhooks[] | select(.hook_url | contains("ci-system"))'

创建 Webhook 的最佳实践

# 1. 先查看支持的事件
gitlink-cli webhook +events

# 2. 创建 Webhook 并验证
gitlink-cli webhook +create --owner $OWNER --repo $REPO --url $URL --events $EVENTS

# 3. 测试 Webhook 是否正常工作
gitlink-cli webhook +test --owner $OWNER --repo $REPO --id $WEBHOOK_ID

安全建议

• 使用密钥: 为 Webhook 设置密钥以验证请求来源
• HTTPS: 始终使用 HTTPS URL 作为 Webhook 回调地址
• 最小权限: 只监听必要的事件类型
• 定期轮换: 定期更新 Webhook 密钥

参考文档

• webhook-list.md - 列出 Webhook 详细说明
• webhook-create.md - 创建 Webhook 详细说明
• webhook-update.md - 更新 Webhook 详细说明
• webhook-delete.md - 删除 Webhook 详细说明
• webhook-test.md - 测试 Webhook 详细说明
• webhook-info.md - 查看 Webhook 详细说明
• examples/webhook-workflow.md - 完整工作流示例

注意事项

1. API 限制: GitLink 对 Webhook 数量有限制，通常每个仓库不超过 20 个
2. URL 要求: Webhook URL 必须是公网可访问的 HTTPS 地址
3. 超时设置: Webhook 请求超时时间为 10 秒
4. 重试机制: GitLink 会在失败时重试 3 次，间隔分别为 1s、5s、10s
5. 事件顺序: 同一事件的多个 Webhook 按创建顺序依次触发
6. 测试限制: 测试 Webhook 不会触发实际的业务逻辑，仅验证连通性

故障排除

Webhook 未触发

1. 检查 Webhook 是否激活：gitlink-cli webhook +info --id <id> --active true
2. 验证事件类型是否正确：gitlink-cli webhook +info --id <id>
3. 测试 Webhook 连通性：gitlink-cli webhook +test --id <id>

Webhook 响应异常

1. 检查回调服务器是否正常运行
2. 验证 Webhook URL 是否可访问
3. 查看 GitLink 服务器日志确认请求是否发送

权限问题

1. 确认当前用户是仓库管理员或所有者
2. 检查 Token 是否有足够权限：gitlink-cli auth status