github

GitHub Issue 管理机器人

📝 项目简介

通过飞书机器人管理 GitHub Issues，支持创建、更新、关闭 Issue，实时追踪代码完成进度，并将 GitHub 事件同步推送到飞书群聊，实现高效的项目管理和团队协作。

✨ 功能特性

Issue 管理

• 📋 创建 Issue - 通过飞书指令快速创建 GitHub Issue
• ✅ 关闭 Issue - 一键关闭已完成的 Issue
• 🔄 更新 Issue - 修改 Issue 标题、描述、标签、里程碑等
• 🏷️ 标签管理 - 添加/删除 Issue 标签
• 👥 分配任务 - 分配 Issue 给团队成员
• 💬 评论同步 - GitHub 评论实时同步到飞书

进度追踪

• 📊 进度统计 - 实时统计 Issue 完成情况
• 📈 里程碑追踪 - 跟踪里程碑进度
• 🎯 任务看板 - 可视化展示任务状态（待办/进行中/已完成）
• ⏱️ 周期报告 - 定期生成项目进度报告
• 🔔 截止提醒 - Issue 截止日期临近时自动提醒

事件通知

• 🔔 实时推送 - GitHub 事件实时推送到飞书
  • Issue 创建/更新/关闭
  • Pull Request 状态变更
  • Code Review 请求
  • Commit 推送通知
  • Release 发布通知
• 📌 @提醒 - 相关人员自动 @提醒
• 🎨 富文本卡片 - 精美的消息卡片展示

🏗️ 技术架构

• GitHub API - 使用 GitHub REST API 和 GraphQL API
• Webhook 监听 - 接收 GitHub 事件推送
• 飞书机器人 - 飞书开放平台消息 API 和卡片消息
• 数据存储 - PostgreSQL 存储 Issue 状态和映射关系
• 定时任务 - 定期同步 Issue 状态和生成报告

🚀 快速开始

前置要求

• Python 3.8+
• GitHub Personal Access Token（需要 repo 权限）
• 飞书开放平台应用凭证
• PostgreSQL 数据库
• 公网可访问的服务器（用于接收 GitHub Webhook）

安装依赖

pip install -r requirements.txt

配置说明

1. 复制配置文件模板

cp config.example.yaml config.yaml

2. 配置 GitHub 信息

github:
  token: "ghp_your_personal_access_token"
  webhook_secret: "your_webhook_secret"
  repositories:  # 要管理的仓库列表
    - owner: "your-org"
      repo: "your-repo"
      feishu_chat_id: "chat_id_1"  # 对应的飞书群ID
    - owner: "your-org"
      repo: "another-repo"
      feishu_chat_id: "chat_id_2"

3. 配置飞书应用信息

feishu:
  app_id: "your_app_id"
  app_secret: "your_app_secret"
  verification_token: "your_verification_token"
  encrypt_key: "your_encrypt_key"

4. 配置数据库连接

database:
  host: "localhost"
  port: 5432
  username: "your_username"
  password: "your_password"
  database: "github_bot"

5. 配置 Webhook 服务

webhook:
  host: "0.0.0.0"
  port: 8080
  public_url: "https://your-domain.com"  # GitHub Webhook 回调地址

设置 GitHub Webhook

1. 进入 GitHub 仓库设置页面
2. 导航到 Settings > Webhooks > Add webhook
3. 配置 Webhook：
   • Payload URL: https://your-domain.com/webhook/github
   • Content type: application/json
   • Secret: 与配置文件中的 webhook_secret 一致
   • Events: 选择需要监听的事件
     • Issues
     • Pull requests
     • Issue comments
     • Pushes
     • Releases

运行

python main.py

💬 飞书指令

在飞书群聊中使用以下指令与机器人交互：

Issue 管理指令

# 创建 Issue
/issue create <仓库> <标题>
描述内容...

# 示例
/issue create myrepo 修复登录页面bug
登录页面在Chrome浏览器下显示异常

# 关闭 Issue
/issue close <仓库> #<issue号>
/issue close myrepo #123

# 重新打开 Issue
/issue reopen <仓库> #<issue号>

# 添加标签
/issue label <仓库> #<issue号> add <标签1> <标签2>
/issue label myrepo #123 add bug priority-high

# 分配任务
/issue assign <仓库> #<issue号> @<成员>
/issue assign myrepo #123 @张三

# 添加评论
/issue comment <仓库> #<issue号>
评论内容...

查询指令

# 查看仓库所有开放的 Issue
/issue list <仓库>
/issue list myrepo

# 查看我的 Issue
/issue mine

# 查看指定标签的 Issue
/issue search <仓库> label:<标签>
/issue search myrepo label:bug

# 查看项目进度
/progress <仓库>
/progress myrepo

# 查看里程碑进度
/milestone <仓库> <里程碑名称>
/milestone myrepo v1.0

📊 数据存储结构

Issue 映射表 (issue_mapping)

字段名	类型	说明
id	Integer	主键
github_repo	String	GitHub 仓库（owner/repo）
issue_number	Integer	Issue 编号
issue_id	BigInteger	GitHub Issue ID
feishu_message_id	String	飞书消息ID
status	String	状态（open/closed）
created_at	DateTime	创建时间
updated_at	DateTime	更新时间

仓库配置表 (repo_config)

字段名	类型	说明
id	Integer	主键
github_owner	String	仓库所有者
github_repo	String	仓库名称
feishu_chat_id	String	对应的飞书群ID
enabled	Boolean	是否启用
notify_events	JSON	需要通知的事件类型
created_at	DateTime	创建时间

🎯 使用场景

场景 1: 敏捷开发团队

• 在每日站会中通过飞书快速创建 Issue
• 实时同步开发进度到团队群
• 自动提醒即将到期的任务

场景 2: Bug 追踪

• 测试团队在飞书提交 Bug
• 自动创建 GitHub Issue 并分配给开发
• Bug 修复后自动通知测试验证

场景 3: 项目管理

• 里程碑进度自动播报
• 每周生成项目进度报告
• PR Review 请求自动提醒相关人员

场景 4: 开源项目协作

• 新 Issue 自动推送到维护者群
• 社区贡献实时通知
• Release 发布自动宣传

📈 进度统计示例

机器人会以卡片形式展示项目进度：

📊 myrepo 项目进度报告

本周统计 (2026-01-01 ~ 2026-01-07)
━━━━━━━━━━━━━━━━━━━━
✅ 已完成: 15 个 Issue
🔄 进行中: 8 个 Issue  
📋 待处理: 23 个 Issue
⏰ 逾期: 2 个 Issue

里程碑进度
━━━━━━━━━━━━━━━━━━━━
v1.0 Release: ████████░░ 80% (12/15)
v1.1 Planning: ███░░░░░░░ 30% (3/10)

本周活跃贡献者
━━━━━━━━━━━━━━━━━━━━
👨‍💻 张三: 8 commits, 3 PR
👨‍💻 李四: 5 commits, 2 PR
👨‍💻 王五: 3 commits, 1 PR

🔔 事件通知示例

Issue 创建通知

🆕 新 Issue 创建

myrepo #123
━━━━━━━━━━━━━━━━━━━━
标题: 修复登录页面显示bug
创建者: @张三
标签: bug, priority-high

📝 描述:
登录页面在Chrome浏览器下显示异常，
需要紧急修复。

[查看详情] [我来处理]

PR Review 请求

👀 Code Review 请求

myrepo #456
━━━━━━━━━━━━━━━━━━━━
标题: feat: 添加用户权限管理
作者: @李四
请求审查: @张三 @王五

📊 变更:
+258 -120 (6 files)

[去审查] [稍后提醒我]

⚙️ 高级配置

自定义通知规则

notification_rules:
  # Issue 创建时@所有人
  issue_created:
    mention_all: false
    mention_users: []
    
  # 高优先级 Issue @指定人员
  high_priority_issue:
    labels: ["priority-high", "urgent"]
    mention_users: ["user_id_1", "user_id_2"]
    
  # PR 需要审查时@审查人
  pr_review_requested:
    auto_mention: true

定时任务配置

scheduled_tasks:
  # 每日进度报告
  daily_report:
    enabled: true
    time: "09:00"
    timezone: "Asia/Shanghai"
    
  # 每周统计
  weekly_summary:
    enabled: true
    day: "Monday"
    time: "10:00"
    
  # 逾期提醒
  overdue_reminder:
    enabled: true
    interval: "1h"  # 每小时检查一次

⚠️ 注意事项

• GitHub Token 权限

  • 需要 repo 权限读写 Issue
  • 私有仓库需要完整 repo 权限
  • 组织仓库可能需要额外授权

• Webhook 安全

  • 务必配置 webhook_secret 验证请求来源
  • 使用 HTTPS 保护传输安全
  • 定期轮换 secret

• API 限流

  • GitHub API 有速率限制（5000次/小时）
  • 合理使用缓存减少 API 调用
  • 监控 API 用量避免超限

• 数据同步

  • 定期同步确保数据一致性
  • 处理网络异常和重试机制
  • 记录同步日志便于排查问题

• 权限控制

  • 限制只有群成员可以操作 Issue
  • 敏感操作需要管理员权限
  • 记录操作日志便于审计

🔧 故障排查

Webhook 未触发

• 检查 GitHub Webhook 配置是否正确
• 验证公网地址是否可访问
• 查看 GitHub Webhook 发送历史
• 检查防火墙和安全组配置

Issue 创建失败

• 验证 GitHub Token 权限
• 检查仓库名称是否正确
• 确认网络连接正常
• 查看错误日志获取详细信息

消息未推送到飞书

• 验证飞书应用配置
• 确认机器人已加入目标群聊
• 检查 chat_id 是否正确
• 查看飞书 API 调用日志

📚 相关文档

• GitHub REST API 文档
• GitHub Webhooks 文档
• 飞书开放平台文档
• 飞书消息卡片搭建指南

📄 许可证

详见项目根目录 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request

📞 联系方式

如有问题或建议，请通过 Issue 反馈