GitHub webhook notification service for Zhin.js
npm install @zhin.js/plugin-github-notify为 Zhin.js 提供 GitHub 仓库事件通知功能。支持好友或群管理订阅仓库的 push、issue、star、fork、unstar、PR 等事件。
- ✅ 支持多种事件类型:push、issue、star、fork、unstar、pull_request
- ✅ 基于 GitHub Webhook 实时推送
- ✅ 权限控制:仅好友或群管理可订阅
- ✅ 多平台支持:适配所有 Zhin 适配器
- ✅ 数据持久化:使用数据库存储订阅信息
- ✅ 签名验证:支持 Webhook Secret 验证
``bash`
pnpm add @zhin.js/plugin-github-notify
在 zhin.config.ts 中添加插件:
`typescript`
export default defineConfig({
plugins: [
'http', // 必需:提供 HTTP 服务
'adapter-process', // 或其他适配器
'github-notify' // GitHub 通知插件
],
plugin_config: {
'github-notify': {
webhook_secret: 'your-webhook-secret' // 可选:Webhook 签名密钥
}
}
})
订阅所有事件:
``
github.subscribe zhinjs/zhin
订阅指定事件:
``
github.subscribe zhinjs/zhin push issue star
订阅 PR 事件:
``
github.subscribe zhinjs/zhin pr
``
github.list
``
github.unsubscribe zhinjs/zhin
在聊天中使用命令订阅仓库后,会收到提示信息。
1. 访问仓库设置页面:https://github.com/owner/repo/settings/hookshttp://your-domain:port/api/github/webhook
2. 点击 "Add webhook"
3. 填写配置:
- Payload URL: application/json
- Content type: webhook_secret
- Secret: 与插件配置中的 保持一致(可选)
- Events: 选择需要的事件类型
- Just the push event(仅 push)
- Send me everything(所有事件)
- Let me select individual events(自定义选择)
- Pushes
- Issues
- Stars
- Forks
- Pull requests
配置完成后,GitHub 会发送一个测试 Webhook。如果成功,你将在日志中看到:
``
收到 GitHub Webhook: ping - owner/repo
之后任何符合订阅的事件都会自动推送到订阅的聊天中。
| 事件类型 | 命令参数 | GitHub 事件 | 说明 |
|---------|---------|------------|------|
| Push | push | push | 代码推送 |issue
| Issue | | issues | Issue 创建/更新/关闭 |star
| Star | | star (created) | 仓库被 star |unstar
| Unstar | | star (deleted) | 仓库被 unstar |fork
| Fork | | fork | 仓库被 fork |pr
| Pull Request | / pull_request | pull_request | PR 创建/更新/合并 |
📦 zhinjs/zhin
🌿 username pushed to main📝 3 commits:
• abc1234 feat: add new feature
• def5678 fix: resolve bug
• ghi9012 docs: update README
🔗 https://github.com/zhinjs/zhin/tree/main
`$3
`
🐛 zhinjs/zhin
👤 username 打开了 issue #123📌 Bug: Something is broken
🔗 https://github.com/zhinjs/zhin/issues/123
`$3
`
⭐ zhinjs/zhin
👤 username starred the repository🔗 https://github.com/zhinjs/zhin
`$3
`
🍴 zhinjs/zhin
👤 username forked to username/zhin🔗 https://github.com/username/zhin
`$3
`
🔀 zhinjs/zhin
👤 username 打开了 PR #456📌 feat: Add awesome feature
🔗 https://github.com/zhinjs/zhin/pull/456
`权限控制
- 私聊: 所有好友都可以订阅
- 群聊: 仅群管理员可以订阅(需要适配器支持权限检查)
数据库结构
$3
| 字段 | 类型 | 说明 |
|------|------|------|
| id | integer | 主键 |
| repo | text | 仓库名 (owner/repo) |
| events | json | 订阅的事件列表 |
| target_id | text | 目标 ID(用户或群) |
| target_type | text | 类型 (private/group) |
| adapter | text | 适配器名称 |
| bot | text | 机器人名称 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
$3
| 字段 | 类型 | 说明 |
|------|------|------|
| id | integer | 主键 |
| repo | text | 仓库名 |
| event_type | text | 事件类型 |
| payload | json | 事件载荷 |
| created_at | datetime | 创建时间 |
API 端点
$3
接收 GitHub Webhook 事件。
Headers:
-
X-GitHub-Event: 事件类型
- X-Hub-Signature-256: 签名(如果配置了 secret)Body: GitHub Webhook Payload (JSON)
Response:
`json
{
"message": "OK",
"notified": 3
}
`开发
$3
`bash
pnpm build
`$3
`bash
使用 ngrok 或其他工具暴露本地端口
ngrok http 8086使用生成的 URL 配置 GitHub Webhook
例如: https://abc123.ngrok.io/api/github/webhook
``MIT
欢迎提交 Issue 和 Pull Request!