forked from Gitlink/gitlink-cli
234 lines
7.9 KiB
Markdown
234 lines
7.9 KiB
Markdown
---
|
||
name: gitlink-webhook
|
||
version: 1.0.0
|
||
description: "Webhook 管理：创建、查看、更新、删除、测试 Webhook，配置自动化触发器。当用户需要配置 GitLink 仓库的 Webhook 自动化通知时触发。"
|
||
metadata:
|
||
requires:
|
||
bins: ["gitlink-cli"]
|
||
cliHelp: "gitlink-cli webhook --help"
|
||
---
|
||
|
||
# gitlink-webhook（Webhook 操作）
|
||
|
||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||
**CRITICAL — 所有 Shortcuts 在执行写入/删除操作前，务必先确认用户意图。**
|
||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。`gh` 仅适用于 GitHub 平台。**
|
||
|
||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../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` | 标签事件 | 创建或删除标签时 |
|
||
|
||
## 使用示例
|
||
|
||
### 基本操作
|
||
|
||
```bash
|
||
# 列出仓库的所有 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
|
||
|
||
```bash
|
||
# 创建基本的 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
|
||
|
||
```bash
|
||
# 更新 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
|
||
```
|
||
|
||
### 测试和删除
|
||
|
||
```bash
|
||
# 测试 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 自动化
|
||
|
||
```bash
|
||
# 为 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 通知
|
||
|
||
```bash
|
||
# 创建 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 审查通知
|
||
|
||
```bash
|
||
# 创建 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. 认证错误
|
||
```bash
|
||
Error: [401] Authentication failed
|
||
```
|
||
**解决方案**: 运行 `gitlink-cli auth login` 重新认证
|
||
|
||
#### 2. 权限不足
|
||
```bash
|
||
Error: [403] You are not authorized to manage webhooks
|
||
```
|
||
**解决方案**: 确认您对仓库有管理员权限
|
||
|
||
#### 3. 无效的事件类型
|
||
```bash
|
||
Error: no valid events specified
|
||
```
|
||
**解决方案**: 使用 `gitlink-cli webhook +events` 查看支持的事件类型
|
||
|
||
#### 4. Webhook 不存在
|
||
```bash
|
||
Error: [404] Webhook not found
|
||
```
|
||
**解决方案**: 使用 `gitlink-cli webhook +list` 确认 Webhook ID 是否正确
|
||
|
||
## AI Agent 使用指南
|
||
|
||
### 检查现有 Webhook
|
||
```bash
|
||
# 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 的最佳实践
|
||
```bash
|
||
# 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`](references/webhook-list.md) - 列出 Webhook 详细说明
|
||
- [`webhook-create.md`](references/webhook-create.md) - 创建 Webhook 详细说明
|
||
- [`webhook-update.md`](references/webhook-update.md) - 更新 Webhook 详细说明
|
||
- [`webhook-delete.md`](references/webhook-delete.md) - 删除 Webhook 详细说明
|
||
- [`webhook-test.md`](references/webhook-test.md) - 测试 Webhook 详细说明
|
||
- [`webhook-info.md`](references/webhook-info.md) - 查看 Webhook 详细说明
|
||
- [`examples/webhook-workflow.md`](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`
|