Merge pull request '新增 gitlink-notification-bridge Skill' (#293) from wdgde/gitlink-cli:feature/webhook into master
This commit is contained in:
commit
269469b6bc
|
|
@ -0,0 +1,607 @@
|
|||
# gitlink-notification-bridge 使用样例
|
||||
|
||||
## 样例 1：飞书群机器人配置（基础场景）
|
||||
|
||||
**日期**：2026-06-26
|
||||
**用户**：developer
|
||||
**CLI 版本**：gitlink-cli 0.1.18
|
||||
**场景**：将 GitLink 仓库的代码推送事件推送到飞书开发群
|
||||
|
||||
### 执行流程
|
||||
|
||||
```bash
|
||||
# Step 1: 获取飞书群机器人 Webhook URL
|
||||
# （在飞书群聊中操作）
|
||||
# 1. 打开群设置 → 群机器人 → 添加机器人
|
||||
# 2. 选择「自定义机器人」
|
||||
# 3. 复制 Webhook 地址
|
||||
# → https://open.feishu.cn/open-apis/bot/v2/hook/abc123def456
|
||||
|
||||
# Step 2: 创建 Webhook（仅监听 master 和 main 分支）
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/abc123def456" \
|
||||
--type "feishu" \
|
||||
--events "push" \
|
||||
--branch-filter "master,main" \
|
||||
--active "true" \
|
||||
--format json
|
||||
|
||||
# Step 3: 验证配置
|
||||
# 获取刚创建的 Webhook ID
|
||||
gitlink-cli webhook +list --format json
|
||||
|
||||
# 发送测试事件
|
||||
gitlink-cli webhook +test --id 12345 --format json
|
||||
|
||||
# 检查投递历史
|
||||
gitlink-cli webhook +history --id 12345 --format json
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
**创建成功响应：**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 12345,
|
||||
"url": "https://open.feishu.cn/open-apis/bot/v2/hook/abc123def456",
|
||||
"type": "feishu",
|
||||
"events": ["push"],
|
||||
"branch_filter": "master,main",
|
||||
"active": true,
|
||||
"created_at": "2026-06-26T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**测试投递成功：**
|
||||
|
||||
```json
|
||||
{
|
||||
"webhook_id": 12345,
|
||||
"test_event": "push",
|
||||
"delivery_status": "success",
|
||||
"http_status": 200,
|
||||
"response_time_ms": 245
|
||||
}
|
||||
```
|
||||
|
||||
**飞书群消息示例：**
|
||||
|
||||
```
|
||||
📦 代码推送通知
|
||||
|
||||
仓库：myorg/myproject
|
||||
分支：master
|
||||
提交者：developer
|
||||
提交数：3
|
||||
|
||||
最新提交：
|
||||
• feat: 添加用户认证模块 (abc1234)
|
||||
• fix: 修复登录页面样式 (def5678)
|
||||
• docs: 更新 README (ghi9012)
|
||||
|
||||
查看详情：https://www.gitlink.org.cn/myorg/myproject
|
||||
```
|
||||
|
||||
### 关键发现
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| Webhook 类型 | `feishu` |
|
||||
| 支持事件 | `push`, `pull_request_only`, `issues_only` 等 |
|
||||
| 分支过滤 | 支持 `*`, `master`, `feature/*` 等通配符 |
|
||||
| 投递延迟 | < 500ms（正常情况） |
|
||||
| 消息格式 | 飞书卡片消息（自动适配） |
|
||||
|
||||
---
|
||||
|
||||
## 样例 2：钉钉群机器人配置（带签名验证）
|
||||
|
||||
**日期**：2026-06-26
|
||||
**场景**：将 GitLink 仓库的 PR 和 Issue 事件推送到钉钉运维群，启用签名验证
|
||||
|
||||
### 执行流程
|
||||
|
||||
```bash
|
||||
# Step 1: 获取钉钉群机器人 Webhook URL 和 Secret
|
||||
# （在钉钉群聊中操作）
|
||||
# 1. 群设置 → 智能群助手 → 添加机器人
|
||||
# 2. 选择「自定义」
|
||||
# 3. 安全设置选择「加签」
|
||||
# 4. 复制 Secret：SECxxxxxxxxxxxxxxxxxxxx
|
||||
# 5. 复制 Webhook：https://oapi.dingtalk.com/robot/send?access_token=xyz789
|
||||
|
||||
# Step 2: 创建 Webhook（多事件 + 签名）
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://oapi.dingtalk.com/robot/send?access_token=xyz789" \
|
||||
--type "dingtalk" \
|
||||
--events "push,pull_request_only,issues_only" \
|
||||
--branch-filter "master,main,release-*" \
|
||||
--secret "SECxxxxxxxxxxxxxxxxxxxx" \
|
||||
--active "true" \
|
||||
--format json
|
||||
|
||||
# Step 3: 验证签名配置
|
||||
gitlink-cli webhook +view --id 12346 --format json
|
||||
|
||||
# Step 4: 发送测试事件
|
||||
gitlink-cli webhook +test --id 12346 --format json
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
**创建成功响应：**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 12346,
|
||||
"url": "https://oapi.dingtalk.com/robot/send?access_token=xyz789",
|
||||
"type": "dingtalk",
|
||||
"events": ["push", "pull_request_only", "issues_only"],
|
||||
"branch_filter": "master,main,release-*",
|
||||
"secret": "********", // 已脱敏
|
||||
"active": true,
|
||||
"created_at": "2026-06-26T11:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**钉钉群消息示例（PR 事件）：**
|
||||
|
||||
```
|
||||
🔀 Pull Request 通知
|
||||
|
||||
仓库：myorg/myproject
|
||||
标题：feat: 添加用户认证模块
|
||||
作者：developer
|
||||
状态：待审核
|
||||
|
||||
PR #42
|
||||
分支：feature/auth → master
|
||||
|
||||
查看详情：https://www.gitlink.org.cn/myorg/myproject/pulls/42
|
||||
```
|
||||
|
||||
### 签名验证说明
|
||||
|
||||
钉钉机器人使用「加签」安全设置时，GitLink 会自动计算签名：
|
||||
|
||||
```
|
||||
签名算法：HmacSHA256(timestamp + "\n" + secret, secret)
|
||||
请求头：X-Timestamp, X-Sign
|
||||
```
|
||||
|
||||
**注意事项：**
|
||||
- Secret 必须与钉钉机器人设置中的「加签密钥」完全一致
|
||||
- 签名验证失败会返回 HTTP 403
|
||||
- 建议先测试无签名配置，确认可用后再启用签名
|
||||
|
||||
---
|
||||
|
||||
## 样例 3：多群通知配置
|
||||
|
||||
**场景**：为不同团队配置不同的通知策略
|
||||
|
||||
### 执行流程
|
||||
|
||||
```bash
|
||||
# 开发群 - 监听所有分支的所有事件
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/dev-group" \
|
||||
--type "feishu" \
|
||||
--events "push,pull_request_only,pull_request_comment,issues_only,issue_comment" \
|
||||
--branch-filter "*" \
|
||||
--active "true" \
|
||||
--format json
|
||||
|
||||
# 运维群 - 仅监听生产分支的推送和分支操作
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/ops-group" \
|
||||
--type "feishu" \
|
||||
--events "push,create,delete" \
|
||||
--branch-filter "master,main,release-*,hotfix-*" \
|
||||
--active "true" \
|
||||
--format json
|
||||
|
||||
# 产品群 - 仅监听 Issue 相关事件
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/product-group" \
|
||||
--type "feishu" \
|
||||
--events "issues_only,issue_comment,issue_assign,issue_label" \
|
||||
--branch-filter "*" \
|
||||
--active "true" \
|
||||
--format json
|
||||
|
||||
# 查看所有 Webhook
|
||||
gitlink-cli webhook +list --format json
|
||||
```
|
||||
|
||||
### 预期输出
|
||||
|
||||
**Webhook 列表：**
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 12347,
|
||||
"url": "https://open.feishu.cn/open-apis/bot/v2/hook/dev-group",
|
||||
"type": "feishu",
|
||||
"events": ["push", "pull_request_only", "pull_request_comment", "issues_only", "issue_comment"],
|
||||
"branch_filter": "*",
|
||||
"active": true
|
||||
},
|
||||
{
|
||||
"id": 12348,
|
||||
"url": "https://open.feishu.cn/open-apis/bot/v2/hook/ops-group",
|
||||
"type": "feishu",
|
||||
"events": ["push", "create", "delete"],
|
||||
"branch_filter": "master,main,release-*,hotfix-*",
|
||||
"active": true
|
||||
},
|
||||
{
|
||||
"id": 12349,
|
||||
"url": "https://open.feishu.cn/open-apis/bot/v2/hook/product-group",
|
||||
"type": "feishu",
|
||||
"events": ["issues_only", "issue_comment", "issue_assign", "issue_label"],
|
||||
"branch_filter": "*",
|
||||
"active": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 样例 4：混合平台配置（飞书 + 钉钉）
|
||||
|
||||
**场景**：同时推送到飞书和钉钉群
|
||||
|
||||
### 执行流程
|
||||
|
||||
```bash
|
||||
# 飞书群
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/feishu-group" \
|
||||
--type "feishu" \
|
||||
--events "push,pull_request_only" \
|
||||
--branch-filter "master,main" \
|
||||
--active "true" \
|
||||
--format json
|
||||
|
||||
# 钉钉群
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://oapi.dingtalk.com/robot/send?access_token=dingtalk-token" \
|
||||
--type "dingtalk" \
|
||||
--events "push,pull_request_only" \
|
||||
--branch-filter "master,main" \
|
||||
--active "true" \
|
||||
--format json
|
||||
|
||||
# 验证两个平台都收到通知
|
||||
gitlink-cli webhook +test --id 12350 --format json # 飞书
|
||||
gitlink-cli webhook +test --id 12351 --format json # 钉钉
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 样例 5：故障排查 - 群聊未收到消息
|
||||
|
||||
**场景**：配置后群聊未收到通知
|
||||
|
||||
### 诊断流程
|
||||
|
||||
```bash
|
||||
# Step 1: 检查 Webhook 是否激活
|
||||
gitlink-cli webhook +view --id 12345 --format json
|
||||
|
||||
# 输出示例：
|
||||
{
|
||||
"id": 12345,
|
||||
"active": false, // ← 问题：未激活
|
||||
"url": "https://open.feishu.cn/open-apis/bot/v2/hook/abc123",
|
||||
"type": "feishu",
|
||||
"events": ["push"]
|
||||
}
|
||||
|
||||
# Step 2: 激活 Webhook
|
||||
gitlink-cli webhook +update \
|
||||
--id 12345 \
|
||||
--active "true" \
|
||||
--format json
|
||||
|
||||
# Step 3: 检查投递历史
|
||||
gitlink-cli webhook +history --id 12345 --format json
|
||||
|
||||
# 输出示例：
|
||||
{
|
||||
"deliveries": [
|
||||
{
|
||||
"id": "d001",
|
||||
"event_type": "push",
|
||||
"delivered_at": "2026-06-26T10:35:00Z",
|
||||
"http_status": 200, // ← 成功
|
||||
"response_time_ms": 180
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
# Step 4: 发送测试事件
|
||||
gitlink-cli webhook +test --id 12345 --format json
|
||||
```
|
||||
|
||||
### 常见问题诊断表
|
||||
|
||||
| 问题 | 检测方式 | 解决方案 |
|
||||
|------|----------|----------|
|
||||
| Webhook 未激活 | `active: false` | `--active "true"` |
|
||||
| URL 错误 | 投递历史 HTTP 404 | 重新获取正确的 Webhook URL |
|
||||
| 签名验证失败 | 投递历史 HTTP 403 | 确保 Secret 与群机器人配置一致 |
|
||||
| 事件未触发 | 分支过滤不匹配 | 更新 `--branch-filter` |
|
||||
| 事件类型不匹配 | 事件订阅不包含 | 更新 `--events` |
|
||||
|
||||
---
|
||||
|
||||
## 样例 6：故障排查 - 签名验证失败
|
||||
|
||||
**场景**：钉钉群机器人返回签名错误
|
||||
|
||||
### 诊断流程
|
||||
|
||||
```bash
|
||||
# Step 1: 检查投递历史
|
||||
gitlink-cli webhook +history --id 12346 --format json
|
||||
|
||||
# 输出示例：
|
||||
{
|
||||
"deliveries": [
|
||||
{
|
||||
"id": "d002",
|
||||
"event_type": "push",
|
||||
"delivered_at": "2026-06-26T11:05:00Z",
|
||||
"http_status": 403, // ← 签名验证失败
|
||||
"error": "signature verification failed"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
# Step 2: 检查当前 Secret 配置
|
||||
gitlink-cli webhook +view --id 12346 --format json
|
||||
|
||||
# Step 3: 更新 Secret（确保与钉钉机器人「加签密钥」一致）
|
||||
gitlink-cli webhook +update \
|
||||
--id 12346 \
|
||||
--secret "SECcorrectsecret123456" \
|
||||
--format json
|
||||
|
||||
# Step 4: 重新测试
|
||||
gitlink-cli webhook +test --id 12346 --format json
|
||||
```
|
||||
|
||||
### 签名验证要点
|
||||
|
||||
**飞书签名：**
|
||||
- 在飞书群机器人设置中启用「签名校验」
|
||||
- 设置自定义 Secret（建议 16-32 位随机字符串）
|
||||
- GitLink 配置相同的 Secret
|
||||
|
||||
**钉钉签名：**
|
||||
- 钉钉机器人创建时选择「加签」安全设置
|
||||
- 系统自动生成 Secret（以 `SEC` 开头）
|
||||
- 完整复制 Secret 到 GitLink 配置
|
||||
|
||||
---
|
||||
|
||||
## 样例 7：更新和删除 Webhook
|
||||
|
||||
**场景**：调整现有配置或清理不再使用的 Webhook
|
||||
|
||||
### 更新配置
|
||||
|
||||
```bash
|
||||
# 更新事件订阅
|
||||
gitlink-cli webhook +update \
|
||||
--id 12345 \
|
||||
--events "push,pull_request_only,issues_only" \
|
||||
--format json
|
||||
|
||||
# 更新分支过滤
|
||||
gitlink-cli webhook +update \
|
||||
--id 12345 \
|
||||
--branch-filter "master,main,develop,feature/*" \
|
||||
--format json
|
||||
|
||||
# 暂停通知（不删除）
|
||||
gitlink-cli webhook +update \
|
||||
--id 12345 \
|
||||
--active "false" \
|
||||
--format json
|
||||
|
||||
# 恢复通知
|
||||
gitlink-cli webhook +update \
|
||||
--id 12345 \
|
||||
--active "true" \
|
||||
--format json
|
||||
```
|
||||
|
||||
### 删除 Webhook
|
||||
|
||||
```bash
|
||||
# ⚠️ 删除前确认
|
||||
gitlink-cli webhook +view --id 12345 --format json
|
||||
|
||||
# 删除
|
||||
gitlink-cli webhook +delete --id 12345 --format json
|
||||
|
||||
# 验证已删除
|
||||
gitlink-cli webhook +list --format json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 样例 8：通过 Agent 调用 Skill（自动配置）
|
||||
|
||||
**日期**：2026-06-26
|
||||
**调用方式**：`Agent(subagent_type="general", prompt="请帮我配置 GitLink 仓库的飞书通知，监听 master 分支的推送事件。")`
|
||||
|
||||
### Agent 自主执行的命令序列
|
||||
|
||||
```
|
||||
工具调用 1: Read → ../gitlink-shared/SKILL.md ← 遵循 Skill 前置条件
|
||||
工具调用 2: Read → ./SKILL.md ← 读取当前 Skill
|
||||
工具调用 3: Bash → gitlink-cli webhook +list --format json ← 检查现有配置
|
||||
工具调用 4: Bash → gitlink-cli webhook +create ... ← 创建 Webhook
|
||||
工具调用 5: Bash → gitlink-cli webhook +test --id ... ← 发送测试
|
||||
工具调用 6: Bash → gitlink-cli webhook +history --id ... ← 验证投递
|
||||
```
|
||||
|
||||
### Agent 决策过程
|
||||
|
||||
Agent **正确遵循了 Skill 工作流**：
|
||||
|
||||
1. 先读取 `gitlink-shared/SKILL.md` 了解认证和安全规则
|
||||
2. 读取当前 Skill 了解配置流程
|
||||
3. 检查现有 Webhook 避免重复创建
|
||||
4. 引导用户获取飞书群机器人 Webhook URL
|
||||
5. 创建 Webhook 并验证配置
|
||||
6. 生成配置摘要报告
|
||||
|
||||
### Agent 生成的配置摘要
|
||||
|
||||
```markdown
|
||||
## GitLink 跨平台通知桥接配置完成
|
||||
|
||||
### 配置概要
|
||||
|
||||
| 项目 | 详情 |
|
||||
|------|------|
|
||||
| 仓库 | myorg/myproject |
|
||||
| 平台 | 飞书 |
|
||||
| Webhook ID | 12345 |
|
||||
| 状态 | ✅ 已激活 |
|
||||
|
||||
### 订阅配置
|
||||
|
||||
| 配置项 | 值 |
|
||||
|--------|-----|
|
||||
| 事件类型 | push |
|
||||
| 分支过滤 | master |
|
||||
| 签名验证 | ❌ 未启用 |
|
||||
|
||||
### 测试结果
|
||||
|
||||
| 测试项 | 结果 |
|
||||
|--------|------|
|
||||
| 测试投递 | ✅ 成功 |
|
||||
| HTTP 状态码 | 200 |
|
||||
| 群聊收到消息 | ✅ 是 |
|
||||
|
||||
### 后续操作
|
||||
|
||||
1. 触发实际推送事件验证
|
||||
2. 监控投递历史：`gitlink-cli webhook +history --id 12345`
|
||||
3. 如需调整，使用 `gitlink-cli webhook +update --id 12345`
|
||||
|
||||
---
|
||||
*由 gitlink-notification-bridge Skill 自动生成*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 异常场景速查
|
||||
|
||||
| 场景 | 检测方式 | 处理 |
|
||||
|------|----------|------|
|
||||
| Webhook URL 格式错误 | 创建时返回 400 | 确保格式正确（飞书：`https://open.feishu.cn/open-apis/bot/v2/hook/xxx`） |
|
||||
| 不支持的 Webhook 类型 | `--type` 参数报错 | 使用 `feishu` 或 `dingtalk` |
|
||||
| 分支过滤语法错误 | 创建时返回 400 | 使用逗号分隔，支持 `*` 通配符 |
|
||||
| 事件类型不存在 | 创建时返回 400 | 参考支持的事件列表 |
|
||||
| 投递超时 | 投递历史显示 timeout | 检查网络连接，重试 |
|
||||
| 消息格式异常 | 群聊显示乱码 | 检查 `--type` 是否正确 |
|
||||
|
||||
---
|
||||
|
||||
## 版本兼容性说明
|
||||
|
||||
本 skill v1.0.0 基于 `gitlink-cli 0.1.18` 编写。
|
||||
|
||||
### 支持的 Webhook 类型
|
||||
|
||||
| 类型 | 说明 | GitLink 版本 |
|
||||
|------|------|--------------|
|
||||
| `feishu` | 飞书群机器人 | v0.1.0+ |
|
||||
| `dingtalk` | 钉钉群机器人 | v0.1.0+ |
|
||||
| `slack` | Slack | v0.1.0+ |
|
||||
| `discord` | Discord | v0.1.0+ |
|
||||
| `telegram` | Telegram | v0.1.0+ |
|
||||
| `msteams` | Microsoft Teams | v0.1.0+ |
|
||||
| `matrix` | Matrix | v0.1.0+ |
|
||||
|
||||
### 支持的事件类型
|
||||
|
||||
| 事件 | 说明 | GitLink 版本 |
|
||||
|------|------|--------------|
|
||||
| `push` | 代码推送 | v0.1.0+ |
|
||||
| `create` | 创建分支/标签 | v0.1.0+ |
|
||||
| `delete` | 删除分支/标签 | v0.1.0+ |
|
||||
| `issues_only` | Issue 创建/更新 | v0.1.0+ |
|
||||
| `issue_assign` | Issue 分配 | v0.1.0+ |
|
||||
| `issue_label` | Issue 标签变更 | v0.1.0+ |
|
||||
| `issue_comment` | Issue 评论 | v0.1.0+ |
|
||||
| `pull_request_only` | PR 创建/更新 | v0.1.0+ |
|
||||
| `pull_request_assign` | PR 分配 | v0.1.0+ |
|
||||
| `pull_request_comment` | PR 评论 | v0.1.0+ |
|
||||
|
||||
当 CLI 版本更新后，重新验证可用命令：
|
||||
|
||||
```bash
|
||||
gitlink-cli webhook --help
|
||||
gitlink-cli webhook +create --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 安全配置
|
||||
|
||||
- ✅ 生产环境建议启用签名验证
|
||||
- ✅ Secret 使用 16-32 位随机字符串
|
||||
- ✅ 定期轮换 Secret（建议每季度）
|
||||
- ⚠️ 不要在公开仓库中暴露 Webhook URL
|
||||
|
||||
### 2. 事件订阅策略
|
||||
|
||||
| 团队类型 | 推荐事件 | 说明 |
|
||||
|----------|----------|------|
|
||||
| 开发团队 | `push,pull_request_only,pull_request_comment` | 关注代码变更和评审 |
|
||||
| 运维团队 | `push,create,delete` | 关注分支和版本管理 |
|
||||
| 产品团队 | `issues_only,issue_comment` | 关注需求和问题跟踪 |
|
||||
| QA 团队 | `pull_request_only,issues_only` | 关注测试任务 |
|
||||
|
||||
### 3. 分支过滤策略
|
||||
|
||||
| 环境 | 推荐过滤规则 | 说明 |
|
||||
|------|--------------|------|
|
||||
| 生产环境 | `master,main,release-*` | 仅监听关键分支 |
|
||||
| 开发环境 | `*` 或 `feature/*,develop` | 监听所有或开发分支 |
|
||||
| 测试环境 | `test-*` | 仅监听测试分支 |
|
||||
|
||||
### 4. 监控和维护
|
||||
|
||||
```bash
|
||||
# 定期检查投递成功率
|
||||
gitlink-cli webhook +history --id <id> --format json | jq '.deliveries | map(select(.http_status != 200)) | length'
|
||||
|
||||
# 批量检查所有 Webhook 状态
|
||||
gitlink-cli webhook +list --format json | jq '.[] | {id, active, type}'
|
||||
|
||||
# 清理未激活的 Webhook
|
||||
gitlink-cli webhook +list --format json | jq '.[] | select(.active == false) | .id' | xargs -I {} gitlink-cli webhook +delete --id {}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [飞书机器人开发文档](https://open.feishu.cn/document/ukTMukTMukTM/ucTM5YjL3ETO24yNxkjN)
|
||||
- [钉钉机器人开发文档](https://open.dingtalk.com/document/robots/custom-robot-access)
|
||||
- [GitLink Webhook API 文档](https://www.gitlink.org.cn/docs/api#webhook)
|
||||
- [gitlink-webhook-sentinel Skill](../gitlink-webhook-sentinel/SKILL.md) - Webhook 监控和故障诊断
|
||||
|
|
@ -0,0 +1,447 @@
|
|||
---
|
||||
name: gitlink-notification-bridge
|
||||
version: 1.0.0
|
||||
description: "跨平台通知桥接：将 GitLink 仓库事件实时推送到飞书/钉钉群机器人，实现跨平台协作通知。当用户需要配置 GitLink 与飞书/钉钉集成时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "gitlink-cli webhook --help"
|
||||
---
|
||||
|
||||
# gitlink-notification-bridge（跨平台通知桥接）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 所有写入/删除操作前，务必先确认用户意图。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
|
||||
> **执行样例：** 参见 [`EXAMPLES.md`](EXAMPLES.md)
|
||||
|
||||
---
|
||||
|
||||
## 功能概述
|
||||
|
||||
帮助用户快速配置 GitLink 仓库与飞书/钉钉群机器人的集成，实现：
|
||||
|
||||
1. **实时推送** — 代码推送、PR、Issue 等事件实时推送到群聊
|
||||
2. **多平台支持** — 支持飞书（Feishu）和钉钉（DingTalk）
|
||||
3. **事件过滤** — 可选择订阅特定事件类型
|
||||
4. **分支过滤** — 可限定监听特定分支的推送
|
||||
5. **安全验证** — 支持 Webhook Secret 签名验证
|
||||
|
||||
---
|
||||
|
||||
## 支持的平台
|
||||
|
||||
| 平台 | Webhook 类型 | 官方文档 |
|
||||
|------|-------------|----------|
|
||||
| **飞书** | `feishu` | [飞书机器人开发文档](https://open.feishu.cn/document/ukTMukTMukTM/ucTM5YjL3ETO24yNxkjN) |
|
||||
| **钉钉** | `dingtalk` | [钉钉机器人开发文档](https://open.dingtalk.com/document/robots/custom-robot-access) |
|
||||
|
||||
---
|
||||
|
||||
## 工作流：快速配置通知桥接
|
||||
|
||||
### Step 1：获取群机器人 Webhook URL
|
||||
|
||||
#### 飞书群机器人
|
||||
|
||||
1. 打开飞书群聊 → 点击群设置 → 群机器人 → 添加机器人
|
||||
2. 选择「自定义机器人」
|
||||
3. 设置机器人名称和描述
|
||||
4. 复制 Webhook 地址（格式：`https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx`）
|
||||
5. （可选）设置签名密钥，增强安全性
|
||||
|
||||
#### 钉钉群机器人
|
||||
|
||||
1. 打开钉钉群聊 → 点击群设置 → 智能群助手 → 添加机器人
|
||||
2. 选择「自定义」机器人
|
||||
3. 设置机器人名称
|
||||
4. 安全设置选择「加签」，复制密钥（Secret）
|
||||
5. 复制 Webhook 地址（格式：`https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx`）
|
||||
|
||||
---
|
||||
|
||||
### Step 2：配置 GitLink Webhook
|
||||
|
||||
使用 `gitlink-cli webhook +create` 命令创建 Webhook：
|
||||
|
||||
#### 飞书配置示例
|
||||
|
||||
```bash
|
||||
# 基础配置（推送事件）
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx" \
|
||||
--type "feishu" \
|
||||
--events "push" \
|
||||
--branch-filter "master,main" \
|
||||
--active "true"
|
||||
|
||||
# 完整配置（多事件 + 签名）
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx" \
|
||||
--type "feishu" \
|
||||
--events "push,pull_request_only,issues_only" \
|
||||
--branch-filter "master,main,release-*" \
|
||||
--secret "your-feishu-secret" \
|
||||
--active "true"
|
||||
```
|
||||
|
||||
#### 钉钉配置示例
|
||||
|
||||
```bash
|
||||
# 基础配置（推送事件）
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx" \
|
||||
--type "dingtalk" \
|
||||
--events "push" \
|
||||
--branch-filter "master,main" \
|
||||
--active "true"
|
||||
|
||||
# 完整配置（多事件 + 签名）
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx" \
|
||||
--type "dingtalk" \
|
||||
--events "push,pull_request_only,issues_only" \
|
||||
--branch-filter "master,main,release-*" \
|
||||
--secret "your-dingtalk-secret" \
|
||||
--active "true"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3：验证配置
|
||||
|
||||
#### 发送测试事件
|
||||
|
||||
```bash
|
||||
# 获取 Webhook ID
|
||||
gitlink-cli webhook +list --format json
|
||||
|
||||
# 发送测试事件
|
||||
gitlink-cli webhook +test --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
#### 检查投递历史
|
||||
|
||||
```bash
|
||||
# 查看投递记录
|
||||
gitlink-cli webhook +history --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
**预期结果：**
|
||||
- 群聊中收到测试消息
|
||||
- 投递历史显示 HTTP 200 状态码
|
||||
|
||||
---
|
||||
|
||||
## 事件类型说明
|
||||
|
||||
| 事件 | 说明 | 推荐场景 |
|
||||
|------|------|----------|
|
||||
| `push` | 代码推送 | 监听代码提交 |
|
||||
| `pull_request_only` | PR 创建/更新 | 代码评审流程 |
|
||||
| `pull_request_comment` | PR 评论 | 评审讨论通知 |
|
||||
| `pull_request_assign` | PR 分配 | 任务分配通知 |
|
||||
| `issues_only` | Issue 创建/更新 | 问题跟踪 |
|
||||
| `issue_comment` | Issue 评论 | 问题讨论通知 |
|
||||
| `issue_assign` | Issue 分配 | 任务分配通知 |
|
||||
| `create` | 创建分支/标签 | 版本管理 |
|
||||
| `delete` | 删除分支/标签 | 清理通知 |
|
||||
|
||||
**推荐组合：**
|
||||
|
||||
- **开发团队**：`push,pull_request_only,pull_request_comment`
|
||||
- **运维团队**：`push,create,delete`
|
||||
- **产品团队**：`issues_only,issue_comment`
|
||||
- **全量监控**：`push,pull_request_only,issues_only,create,delete`
|
||||
|
||||
---
|
||||
|
||||
## 分支过滤规则
|
||||
|
||||
`--branch-filter` 参数支持通配符：
|
||||
|
||||
| 过滤规则 | 说明 | 示例 |
|
||||
|----------|------|------|
|
||||
| `*` | 所有分支（默认） | 监听所有分支 |
|
||||
| `master` | 单个分支 | 仅监听 master |
|
||||
| `master,main` | 多个分支 | 监听 master 和 main |
|
||||
| `release-*` | 通配符匹配 | 匹配 release-1.0, release-2.0 |
|
||||
| `feature/*` | 路径匹配 | 匹配 feature/login, feature/api |
|
||||
|
||||
**推荐配置：**
|
||||
|
||||
- **生产环境**：`master,main,release-*`
|
||||
- **开发环境**：`*` 或 `feature/*,develop`
|
||||
- **测试环境**：`test-*`
|
||||
|
||||
---
|
||||
|
||||
## 安全配置
|
||||
|
||||
### Webhook Secret（签名验证）
|
||||
|
||||
GitLink 支持 Webhook Secret 签名验证，防止伪造请求：
|
||||
|
||||
#### 飞书签名
|
||||
|
||||
```bash
|
||||
# 创建时设置 Secret
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx" \
|
||||
--type "feishu" \
|
||||
--events "push" \
|
||||
--secret "your-strong-secret"
|
||||
|
||||
# 更新 Secret
|
||||
gitlink-cli webhook +update \
|
||||
--id <webhook_id> \
|
||||
--secret "new-strong-secret"
|
||||
```
|
||||
|
||||
**注意：** 飞书群机器人需在创建时启用「签名校验」，Secret 需与 GitLink 配置一致。
|
||||
|
||||
#### 钉钉签名
|
||||
|
||||
```bash
|
||||
# 创建时设置 Secret（使用钉钉机器人的加签密钥）
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx" \
|
||||
--type "dingtalk" \
|
||||
--events "push" \
|
||||
--secret "SECxxxxxxxxxxxxxxxxxxxx"
|
||||
```
|
||||
|
||||
**注意：** 钉钉机器人的 Secret 在创建机器人时生成，需完整复制。
|
||||
|
||||
---
|
||||
|
||||
## 高级配置
|
||||
|
||||
### 多群通知
|
||||
|
||||
为不同群聊创建不同的 Webhook：
|
||||
|
||||
```bash
|
||||
# 开发群 - 监听所有事件
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/dev-group" \
|
||||
--type "feishu" \
|
||||
--events "push,pull_request_only,issues_only" \
|
||||
--branch-filter "*"
|
||||
|
||||
# 运维群 - 仅监听生产分支
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/ops-group" \
|
||||
--type "feishu" \
|
||||
--events "push,create,delete" \
|
||||
--branch-filter "master,main,release-*"
|
||||
|
||||
# 产品群 - 仅监听 Issue
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/product-group" \
|
||||
--type "feishu" \
|
||||
--events "issues_only,issue_comment" \
|
||||
--branch-filter "*"
|
||||
```
|
||||
|
||||
### 混合平台配置
|
||||
|
||||
同时推送到飞书和钉钉：
|
||||
|
||||
```bash
|
||||
# 飞书群
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxx" \
|
||||
--type "feishu" \
|
||||
--events "push,pull_request_only" \
|
||||
--branch-filter "master,main"
|
||||
|
||||
# 钉钉群
|
||||
gitlink-cli webhook +create \
|
||||
--url "https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxx" \
|
||||
--type "dingtalk" \
|
||||
--events "push,pull_request_only" \
|
||||
--branch-filter "master,main"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 常见问题
|
||||
|
||||
#### 1. 群聊未收到消息
|
||||
|
||||
**检查步骤：**
|
||||
|
||||
```bash
|
||||
# 1. 检查 Webhook 是否激活
|
||||
gitlink-cli webhook +view --id <webhook_id> --format json
|
||||
|
||||
# 2. 检查投递历史
|
||||
gitlink-cli webhook +history --id <webhook_id> --format json
|
||||
|
||||
# 3. 发送测试事件
|
||||
gitlink-cli webhook +test --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
**可能原因：**
|
||||
- Webhook 未激活（`active: false`）
|
||||
- URL 错误或已失效
|
||||
- 签名验证失败（Secret 不匹配）
|
||||
- 事件未触发（分支过滤或事件订阅不匹配）
|
||||
|
||||
#### 2. 签名验证失败
|
||||
|
||||
**错误表现：** 投递历史显示 HTTP 403 或群聊提示签名错误
|
||||
|
||||
**解决方案：**
|
||||
|
||||
```bash
|
||||
# 检查当前 Secret 配置
|
||||
gitlink-cli webhook +view --id <webhook_id> --format json
|
||||
|
||||
# 更新 Secret（确保与群机器人配置一致）
|
||||
gitlink-cli webhook +update \
|
||||
--id <webhook_id> \
|
||||
--secret "correct-secret"
|
||||
|
||||
# 重新测试
|
||||
gitlink-cli webhook +test --id <webhook_id> --format json
|
||||
```
|
||||
|
||||
#### 3. 消息格式异常
|
||||
|
||||
**可能原因：**
|
||||
- Webhook 类型配置错误（`--type` 应为 `feishu` 或 `dingtalk`）
|
||||
- Content-Type 不匹配（默认 `json`，通常无需修改）
|
||||
|
||||
**解决方案：**
|
||||
|
||||
```bash
|
||||
# 检查类型配置
|
||||
gitlink-cli webhook +view --id <webhook_id> --format json
|
||||
|
||||
# 更新类型
|
||||
gitlink-cli webhook +update \
|
||||
--id <webhook_id> \
|
||||
--type "feishu"
|
||||
```
|
||||
|
||||
#### 4. 特定分支未触发通知
|
||||
|
||||
**检查分支过滤规则：**
|
||||
|
||||
```bash
|
||||
# 查看当前过滤规则
|
||||
gitlink-cli webhook +view --id <webhook_id> --format json
|
||||
|
||||
# 更新过滤规则
|
||||
gitlink-cli webhook +update \
|
||||
--id <webhook_id> \
|
||||
--branch-filter "master,main,feature/*"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 管理操作
|
||||
|
||||
### 查看所有 Webhook
|
||||
|
||||
```bash
|
||||
# 列出仓库所有 Webhook
|
||||
gitlink-cli webhook +list --format json
|
||||
```
|
||||
|
||||
### 更新配置
|
||||
|
||||
```bash
|
||||
# 更新事件订阅
|
||||
gitlink-cli webhook +update \
|
||||
--id <webhook_id> \
|
||||
--events "push,pull_request_only,issues_only"
|
||||
|
||||
# 更新分支过滤
|
||||
gitlink-cli webhook +update \
|
||||
--id <webhook_id> \
|
||||
--branch-filter "master,main"
|
||||
|
||||
# 暂停通知（不删除）
|
||||
gitlink-cli webhook +update \
|
||||
--id <webhook_id> \
|
||||
--active "false"
|
||||
```
|
||||
|
||||
### 删除 Webhook
|
||||
|
||||
```bash
|
||||
# ⚠️ 删除前确认
|
||||
gitlink-cli webhook +delete --id <webhook_id>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 输出模板
|
||||
|
||||
配置完成后，生成配置摘要：
|
||||
|
||||
```markdown
|
||||
## GitLink 跨平台通知桥接配置完成
|
||||
|
||||
### 配置概要
|
||||
|
||||
| 项目 | 详情 |
|
||||
|------|------|
|
||||
| 仓库 | <owner>/<repo> |
|
||||
| 平台 | 飞书 / 钉钉 |
|
||||
| Webhook ID | <id> |
|
||||
| 状态 | ✅ 已激活 |
|
||||
|
||||
### 订阅配置
|
||||
|
||||
| 配置项 | 值 |
|
||||
|--------|-----|
|
||||
| 事件类型 | <events> |
|
||||
| 分支过滤 | <branch_filter> |
|
||||
| 签名验证 | ✅ 已启用 / ❌ 未启用 |
|
||||
|
||||
### 测试结果
|
||||
|
||||
| 测试项 | 结果 |
|
||||
|--------|------|
|
||||
| 测试投递 | ✅ 成功 / ❌ 失败 |
|
||||
| HTTP 状态码 | 200 |
|
||||
| 群聊收到消息 | ✅ 是 / ❌ 否 |
|
||||
|
||||
### 后续操作
|
||||
|
||||
1. 触发实际事件验证（推送代码、创建 PR 等）
|
||||
2. 监控投递历史：`gitlink-cli webhook +history --id <id>`
|
||||
3. 如需调整，使用 `gitlink-cli webhook +update --id <id>`
|
||||
|
||||
---
|
||||
*由 gitlink-notification-bridge Skill 自动生成*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- ✅ **所有命令使用 `--format json`**，确保可解析
|
||||
- ✅ **创建/更新 Webhook 为写操作**，执行前确认参数
|
||||
- ✅ **Secret 需与群机器人配置一致**，否则签名验证失败
|
||||
- ⚠️ **飞书/钉钉 Webhook URL 需从群设置中获取**，无法手动构造
|
||||
- ⚠️ **删除 Webhook 是不可逆操作**，建议先设为未激活测试
|
||||
- ⚠️ **分支过滤区分大小写**，确保分支名称正确
|
||||
|
||||
---
|
||||
|
||||
## 相关 Skill 交叉引用
|
||||
|
||||
| Skill | 关联场景 |
|
||||
|-------|----------|
|
||||
| [`gitlink-shared`](../gitlink-shared/SKILL.md) | 认证、全局参数、安全规则基础 |
|
||||
| [`gitlink-webhook-sentinel`](../gitlink-webhook-sentinel/SKILL.md) | Webhook 监控、故障诊断、安全审计 |
|
||||
| [`gitlink-notification-digest`](../gitlink-notification-digest/SKILL.md) | GitLink 平台内通知摘要 |
|
||||
Loading…
Reference in New Issue