Orbit GitHub Integration Guide: Issue与Pull Request自动同步任务状态
Orbit GitHub Integration Guide: Issue与Pull Request自动同步任务状态
Orbit 是一个开源的自托管团队工作区(Slack/Linear/Notion 的替代品),其 GitHub 集成功能可以让 GitHub 上的 Issue 和 Pull Request 通过 webhook 事件自动创建、更新 Orbit 任务状态,实现研发流程与工作区任务的无缝联动。本指南带你 3 步完成配置,并讲清每种同步规则。
什么是 Orbit 的 GitHub 集成?
在开始之前,先看一下 Orbit 工作区的整体界面——它把任务(Tasks)、文档(Docs)和聊天(Chat)整合在一个应用里:
Orbit 的 GitHub 集成采用「每工作区一个 GitHub App」的架构:
- 工作区 Owner/Admin 在设置页发起 App 注册,Orbit 自动生成 App manifest,GitHub 将 App 凭据(App ID、加密私钥、webhook secret)回传给 Orbit 并加密存储;
- 无需手动创建任何仓库 webhook,也无需 Orbit API token;
- 每个项目只需选择「一个已安装的仓库 + 一个 issue label」,即可开始自动同步。
📌 官方完整说明见 docs/github.md。
同步机制:一个 Label 驱动一切
这是整套集成最核心、也最优雅的设计——用 GitHub label 作为同步开关:
| GitHub 事件 | Orbit 任务行为 |
|---|---|
| 给 Issue / PR 添加项目 label | 自动创建对应任务(含标题、描述、GitHub 链接) |
| 编辑标题或描述 | 任务的标题和描述实时更新 |
| Issue 关闭 / PR 未合并即关闭 | 任务标记为完成 / 取消 |
| 重新打开(reopen) | 任务回到未开始状态 |
| PR 合并(merged) | 任务自动标记为完成 ✅ |
| 移除 label | 暂停同步,任务显示 GitHub sync paused 徽标 |
| 重新添加 label | 在同一个任务上恢复同步 |
几个值得注意的细节:
- 任务标题和描述在 Orbit 侧只读,其他字段(负责人、优先级等)仍可自由编辑;
- 评论不同步,Orbit 也不会把任务编辑回写到 GitHub——同步是单向的(GitHub → Orbit);
- 在 Orbit 中删除任务后,下一次带 label 的 GitHub 事件会恢复同一个任务并应用当前状态;
- ⚠️ 不要在同一个 Issue/PR 上添加两个项目的 label,否则同步会被拒绝(
github_labels_ambiguous冲突)。
服务端对 issues 和 pull_request 两类事件中的 opened / edited / labeled / unlabeled / closed / reopened / synchronize 动作做过滤与匹配,核心逻辑在 apps/server/src/integration_routes.rs,其中通过 label 匹配找到唯一的项目连接:
SELECT project_id, label FROM github_project_connections
WHERE workspace_id = $1 AND repository = $2 AND installation_id = $3
快速上手:3 步完成配置
第 1 步:服务器准备(管理员)
Orbit 需要一个 GitHub 可达的公网 HTTPS 地址(同时提供 UI 与 webhook 端点 /api/v1/integrations/github/webhook):
- 设置服务器规范域名,例如
ORBIT_PUBLIC_ORIGIN=https://orbit.example.com; - 生成 32 字节密钥并配置:
openssl rand -base64 32,存入环境变量ORBIT_APP_KEY(或文件路径ORBIT_APP_KEY_FILE)。⚠️ 该密钥不要进数据库备份,丢失后无法验证 webhook; - 重启 Orbit。
更多部署细节参考 docs/operations.md。本地开发可用 just dev 并配合 HTTPS 隧道,http://127.0.0.1 地址无法注册 GitHub App。
第 2 步:注册 GitHub App(Owner/Admin)
打开 Settings → GitHub:
- 若 App 归属组织,填写 GitHub 组织名;留空则注册为个人 App;
- 点击 Register GitHub App,Orbit 自动跳转 GitHub 的 manifest 注册页(对应 apps/web/src/features/settings/pages/GithubPage.tsx),在 GitHub 侧确认后即可,凭据自动回存;
- 回到设置页点击 Install or change repositories,勾选要同步的仓库完成安装。
第 3 步:连接项目
打开 Tasks → 项目设置 → GitHub(安装后先刷新):
- 选择一个已安装的仓库;
- 填入一个 GitHub label 名称(需在 GitHub 上事先创建同名 label)并保存;
- 同一个仓库可以连接多个项目,只要各项目使用不同的 label;每个项目仅一个仓库连接。
项目级连接卡片由 ProjectGithubCard.tsx 渲染,支持断开连接(选择 "No repository")。
实操示例:从 PR 到任务
配置完成后,日常使用只需一个动作——打 label:
- 团队成员在 GitHub 给某个 PR 添加项目 label
orbit-core; - Orbit 收到
pull_request事件,数秒内在工作区生成任务,标题、描述与 PR 链接自动带入; - PR 被合并时,任务自动变为完成;若 PR 被拒绝关闭,则任务标记为取消;
- 若暂时不想跟踪某个 PR,直接移除 label——任务保留,但显示暂停徽标(见 TaskGithubSyncPaused.tsx),重新添加 label 即可续上同一个任务。
常见问题
Q:GitHub App 注册被拒绝了怎么办? 修复问题后重新点击 Register GitHub App 即可,新尝试会覆盖上次未完成的注册。
Q:Orbit 支持把任务改动同步回 GitHub 吗? 不支持。同步方向是单向的(GitHub → Orbit),Orbit 侧只能编辑同步字段以外的任务属性。
Q:多个项目共用一个仓库可行吗? 可以。每个项目绑定自己的 label,但请确保单个 Issue/PR 上只有一个项目 label。
相关源码与文档位置
| 模块 | 路径 |
|---|---|
| GitHub 集成文档 | docs/github.md |
| webhook 与同步路由 | apps/server/src/integration_routes.rs |
| 工作区 GitHub 设置页 | apps/web/src/features/settings/pages/GithubPage.tsx |
| 项目仓库连接卡片 | apps/web/src/features/tasks/components/ProjectGithubCard.tsx |
| 任务同步核心逻辑 | apps/server/src/repositories/tasks.rs |
💡 小结:Orbit 的 GitHub 集成用「App + label」两步模型替代了传统繁琐的 webhook 配置,让 Issue 与 Pull Request 的生命周期(创建、编辑、关闭、合并)自动映射为 Orbit 任务状态——对自托管团队来说,这是一套开箱即用、零 token 管理的研发任务同步方案。
