Orbit GitHub Integration Guide: Issue与Pull Request自动同步任务状态

原创2026-11-14 17:19:02493 阅读

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 集成同步

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 在同一个任务上恢复同步

几个值得注意的细节:

  1. 任务标题和描述在 Orbit 侧只读,其他字段(负责人、优先级等)仍可自由编辑;
  2. 评论不同步,Orbit 也不会把任务编辑回写到 GitHub——同步是单向的(GitHub → Orbit);
  3. 在 Orbit 中删除任务后,下一次带 label 的 GitHub 事件会恢复同一个任务并应用当前状态;
  4. ⚠️ 不要在同一个 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):

  1. 设置服务器规范域名,例如 ORBIT_PUBLIC_ORIGIN=https://orbit.example.com;
  2. 生成 32 字节密钥并配置:openssl rand -base64 32,存入环境变量 ORBIT_APP_KEY(或文件路径 ORBIT_APP_KEY_FILE)。⚠️ 该密钥不要进数据库备份,丢失后无法验证 webhook;
  3. 重启 Orbit。

更多部署细节参考 docs/operations.md。本地开发可用 just dev 并配合 HTTPS 隧道,http://127.0.0.1 地址无法注册 GitHub App。

第 2 步:注册 GitHub App(Owner/Admin)

打开 Settings → GitHub:

  1. 若 App 归属组织,填写 GitHub 组织名;留空则注册为个人 App;
  2. 点击 Register GitHub App,Orbit 自动跳转 GitHub 的 manifest 注册页(对应 apps/web/src/features/settings/pages/GithubPage.tsx),在 GitHub 侧确认后即可,凭据自动回存;
  3. 回到设置页点击 Install or change repositories,勾选要同步的仓库完成安装。

第 3 步:连接项目

打开 Tasks → 项目设置 → GitHub(安装后先刷新):

  • 选择一个已安装的仓库;
  • 填入一个 GitHub label 名称(需在 GitHub 上事先创建同名 label)并保存;
  • 同一个仓库可以连接多个项目,只要各项目使用不同的 label;每个项目仅一个仓库连接。

项目级连接卡片由 ProjectGithubCard.tsx 渲染,支持断开连接(选择 "No repository")。

实操示例:从 PR 到任务

配置完成后,日常使用只需一个动作——打 label:

  1. 团队成员在 GitHub 给某个 PR 添加项目 label orbit-core;
  2. Orbit 收到 pull_request 事件,数秒内在工作区生成任务,标题、描述与 PR 链接自动带入;
  3. PR 被合并时,任务自动变为完成;若 PR 被拒绝关闭,则任务标记为取消;
  4. 若暂时不想跟踪某个 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 管理的研发任务同步方案。

登录后查看全文
orbit