gitlink-cli/skills/gitlink-webhook/references/webhook-create.md

gitlink-cli webhook +create

创建新的 Webhook，用于自动化通知和集成。

命令格式

gitlink-cli webhook +create \
  --owner OWNER \
  --repo REPO \
  --url URL \
  [--events EVENTS] \
  [--active ACTIVE] \
  [--content_type CONTENT_TYPE] \
  [--secret SECRET] \
  [--description DESCRIPTION]

参数说明

参数	短参数	说明	是否必须	默认值
--owner	-o	仓库所有者	否	自动从 git remote 解析
--repo	-r	仓库名称	否	自动从 git remote 解析
--url	-u	Webhook 回调 URL	是	-
--events	-e	触发事件（逗号分隔）	否	push
--active	-	是否激活	否	true
--content_type	-	内容类型	否	json
--secret	-	HMAC 验证密钥	否	空
--description	-d	Webhook 描述	否	空

事件类型

支持的事件类型（多个事件用逗号分隔）：

• push - 代码推送
• pull_request - Pull 请求
• issue - Issue 事件
• issue_assign - Issue 指派
• issue_comment - Issue 评论
• pull_request_assign - PR 指派
• pull_request_comment - PR 评论
• merge_request - 合并请求
• repository - 仓库事件
• branch - 分支事件
• tag - 标签事件

返回值

成功返回

{
  "ok": true,
  "data": {
    "id": "456",
    "hook_url": "https://example.com/webhook",
    "events": ["push", "pull_request"],
    "is_active": true,
    "content_type": "json",
    "description": "CI/CD webhook",
    "created_at": "2024-01-01T00:00:00Z",
    "project": {
      "owner": "myuser",
      "repo": "myrepo"
    }
  },
  "meta": {
    "identity": "user:myuser"
  }
}

错误返回

{
  "ok": false,
  "error": {
    "code": 400,
    "message": "Invalid webhook URL",
    "suggestion": "Please provide a valid HTTPS URL"
  }
}

使用示例

基本 Webhook

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

# 在 git 仓库目录中创建（自动解析 owner/repo）
gitlink-cli webhook +create --url https://example.com/webhook

多事件 Webhook

# 监听多个事件
gitlink-cli webhook +create \
  --owner myuser --repo myrepo \
  --url https://ci.example.com/webhook \
  --events push,pull_request,issue

# 监听所有 PR 相关事件
gitlink-cli webhook +create \
  --url https://review.example.com/webhook \
  --events pull_request,pull_request_assign,pull_request_comment

带密钥的 Webhook

# 创建带 HMAC 验证密钥的 Webhook
gitlink-cli webhook +create \
  --url https://ci.example.com/webhook \
  --events push \
  --secret my-secret-key-12345

# CI/CD 系统的 Webhook（推荐）
gitlink-cli webhook +create \
  --url https://jenkins.example.com/gitlink-webhook \
  --events push,pull_request \
  --secret jenkins-webhook-secret \
  --description "Jenkins CI trigger"

带描述的 Webhook

# 创建带描述的 Webhook
gitlink-cli webhook +create \
  --url https://notification.example.com/webhook \
  --events issue,issue_comment \
  --description "Issue notifications to Slack"

不激活的 Webhook

# 创建 Webhook 但暂时不激活
gitlink-cli webhook +create \
  --url https://example.com/webhook \
  --events push \
  --active false \
  --description "Webhook for testing"

不同内容类型

# JSON 格式（默认）
gitlink-cli webhook +create --url https://example.com/webhook --content-type json

# Form 格式
gitlink-cli webhook +create --url https://example.com/webhook --content-type form

错误处理

常见错误

1. URL 无效

Error: Invalid webhook URL format

原因: URL 格式不正确或不是 HTTPS 解决方案:

# 使用 HTTPS URL
gitlink-cli webhook +create --url https://example.com/webhook

2. 无效的事件类型

Error: no valid events specified. Supported events: push, pull_request, issue, ...

原因: 指定了不支持的事件类型 解决方案:

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

# 使用正确的事件类型
gitlink-cli webhook +create --url https://example.com/webhook --events push,pull_request

3. 权限不足

Error: [403] You don't have permission to create webhooks

原因: 用户不是仓库管理员 解决方案: 确认您有仓库管理员权限

4. Webhook 数量超限

Error: [400] Webhook limit reached (maximum 20 webhooks per repository)

原因: 仓库的 Webhook 数量已达上限 解决方案:

# 删除不需要的 Webhook
gitlink-cli webhook +delete --id <unused-webhook-id>

最佳实践

1. 安全性

# 始终为 Webhook 设置密钥
gitlink-cli webhook +create \
  --url https://ci.example.com/webhook \
  --events push \
  --secret $(openssl rand -hex 32)

# 使用 HTTPS URL
gitlink-cli webhook +create --url https://example.com/webhook

2. 事件选择

# 只监听必要的事件
gitlink-cli webhook +create \
  --url https://ci.example.com/webhook \
  --events push  # CI 只需要 push 事件

3. 描述清晰

# 添加清晰的描述便于管理
gitlink-cli webhook +create \
  --url https://jenkins.example.com/webhook \
  --events push,pull_request \
  --description "Production CI - Jenkins Pipeline"

AI Agent 使用建议

验证 Webhook 创建

# 创建后立即测试
WEBHOOK_ID=$(gitlink-cli webhook +create --url $URL --events $EVENTS --format json | jq -r '.data.id')
gitlink-cli webhook +test --id $WEBHOOK_ID

# 验证 Webhook 配置
gitlink-cli webhook +info --id $WEBHOOK_ID

检查重复 Webhook

# 检查是否已存在相同 URL 的 Webhook
existing=$(gitlink-cli webhook +list --format json | jq -r '.data.webhooks[] | select(.hook_url == "https://example.com/webhook") | .id')
if [ -n "$existing" ]; then
    echo "Webhook already exists: $existing"
else
    gitlink-cli webhook +create --url https://example.com/webhook
fi

安全建议

1. 使用密钥: 始终设置 --secret 参数以验证请求来源
2. HTTPS: 确保使用 HTTPS URL 保护数据传输
3. 最小权限: 只监听必要的事件类型
4. 定期轮换: 定期更新 Webhook 密钥
5. 监控日志: 监控 Webhook 请求日志以发现异常活动

注意事项

1. URL 要求: Webhook URL 必须是公网可访问的 HTTPS 地址
2. 数量限制: 每个仓库最多 20 个 Webhook
3. 权限要求: 需要仓库管理员权限
4. 事件格式: 多个事件用逗号分隔，不要有空格
5. 立即生效: 创建后立即可用，除非设置 --active false

相关命令

• webhook +list - 列出所有 Webhook
• webhook +update - 更新 Webhook 配置
• webhook +test - 测试 Webhook
• webhook +events - 查看支持的事件类型