GitHub 集成

当你希望 Oratorio 把真实的 GitHub Issue 和 Pull Request 拉进看板时，可以接入 GitHub。Oratorio 能同步工作项、保持卡片更新、展示最新讨论；在你允许回写后，还能把评论、Pull Request 审阅、审阅检查和交付出的 Pull Request 写回 GitHub。

NOTE

如果是第一次设置 Oratorio，请先从 快速开始 开始。本页只讲 GitHub 相关配置。DotCraft 设置见 接入 DotCraft；完整字段说明见 配置参考。

开始之前

你需要准备：

• 目标 GitHub 仓库或组织的访问权限；
• 一个已经安装到目标仓库上的 GitHub App；
• 已经在 DotCraft 中打开并可用的同一个项目；
• 如果想用 Webhook 自动更新看板，还需要一个 GitHub 能访问到的 Oratorio server 地址。

如果 Oratorio 只在你的电脑上本地运行，GitHub 访问不到它，也没关系。手动同步和定时同步仍然可用。

创建或复用 GitHub App

GitHub 集成只使用 GitHub App。Oratorio 会用 App 完成 read sync、评论、 Pull Request 审阅、审阅检查和交付 Pull Request。

在拥有仓库的用户或组织下创建 GitHub App，并且只安装到你希望 Oratorio 访问的仓库。

按你想开启的能力，选择尽量小的权限：

你想做的事	GitHub 中需要允许的权限
导入 Issue 和 Pull Request	Issues read access 与 Pull requests read access
展示 Pull Request 文件和讨论	Pull requests read access
发布 Issue 评论或 Pull Request 审阅	Issues write access 与 Pull requests write access
显示 Oratorio 审阅检查	Checks write access
把实现结果交付成 Pull Request	Contents write access 与 Pull requests write access

为这个 App 生成 private key。你可以把 private key 粘贴到 Oratorio，也可以让 Oratorio 读取本机上的 private key 文件。

在 Oratorio 中添加仓库

打开 Settings → Projects，添加一条 GitHub 仓库。

• 在 GitHub repository 中填入 owner 和仓库名。
• 在 DotCraft workspace 中选择已经交给 DotCraft 使用的本地项目目录。
• 保存设置。

添加仓库后，项目列表下方会出现 GitHub installation profiles。同一个 GitHub owner 下面的仓库会共用一条 profile。

点击 detect 按钮，让 Oratorio 自动查找 installation。若自动查找失败，可以从 GitHub App installation 页面复制 Installation ID 并手动填入。

填写 GitHub 凭据

打开 Settings → Credentials → GitHub credentials。

• GitHub.com 可以保留默认 endpoint。
• 如果使用 GitHub Enterprise，填入你的 GitHub API base 地址。
• 填入 GitHub App ID。
• 填入 private key，或填写 private key path。
• 如果准备使用 Webhook，填入 webhook secret。
• 只有当你希望 Oratorio 写回评论、审阅、检查或交付 Pull Request 时，才打开 GitHub writes。

保存设置。如果 Oratorio 提示需要重启，请先重启本地 server，再测试连接。

添加 GitHub Webhook

Webhook 对同步不是必需的，但 GitHub Pull Request 评论命令必须使用 Webhook。

对于 server deployment，先启用受限的 HTTPS gateway：

oratorio server webhook enable --public-host webhooks.example.com

命令会输出公网 URL，并且只在首次生成时显示一次 secret；它不会修改 GitHub App。DNS、公网 IP、certificate、firewall、status 和 disable 行为见 服务器部署。

在 GitHub App 的 Webhook 设置中：

• 打开 Active；
• 将 Webhook URL 设置为 https://<host-or-ip>/api/v1/sources/github/webhook；
• 粘贴 CLI 为 Oratorio 保存的同一个 secret；
• 保持 SSL verification 开启；
• 在 Subscribe to events 中选择 Issue comments，并选择同步所需的 Issue、Pull Request、Pull Request review 和 Pull Request review comment 事件。

GitHub App 未订阅 Issue comments 时，Oratorio 无法收到审阅命令。这些 GitHub 设置需要由你手工完成。

如果测试无法到达 Oratorio，通常是因为 GitHub 访问不到你的 Oratorio server。本地桌面会话通常不能直接接收 GitHub cloud 发来的 Webhook。

从 GitHub 请求审阅

有权限的仓库协作者可以在一个开放且已配置的 Pull Request 中发布只包含 以下内容的评论：

@dotcraft-ai review

需要指定一次性的审阅重点时，可以使用：

@dotcraft-ai review for security regressions

dotcraft-ai 是面向用户的公共 Agent 命令身份。接收 Webhook 和发布审阅的 仍然是已经安装的 GitHub App，其结果会显示为 App bot 发布。 dotcraft-ai 不需要成为仓库协作者，也不需要事先参与过该 Pull Request。 如果 GitHub 的 @ 自动补全中没有显示它，请手工输入完整 handle。

命令只有在 GitHub App 已安装、Issue comment 事件和 webhook secret 已配置、 仓库已加入 Oratorio 且仓库有 DotCraft workspace 映射时才会执行。已经关闭或 合并的 Pull Request 不会被调度。

同步与审阅

打开 Settings → Sources 可以查看 GitHub 状态。

• 想立刻导入时，点击 Pull now。
• 想让 Oratorio 定期检查 GitHub，可以开启定时同步。
• 只有在需要重新检查整个仓库时，才使用 full repair。

在 Oratorio 中审阅 GitHub Pull Request 时：

• 通过 会发布 approval，并记录一条通过的 Oratorio 审阅检查。
• 要求修改 会发布审阅反馈，并记录这次 Oratorio 审阅仍需处理。
• 作废 会记录这项工作不应继续推进。

当 implementation draft 准备好后，只要 GitHub writes 已开启且 GitHub App 权限足够，Oratorio 还可以推送分支并创建 Pull Request。

排查

看不到 GitHub 卡片。 检查仓库是否已在 Settings → Projects 中添加、凭据是否已保存，以及 Settings → Sources 是否显示 GitHub 可以读取。

Installation profile 缺失。 确认 GitHub App 已安装到仓库 owner 下。然后回到 Settings → Projects 点击 detect，或手动填写 Installation ID。

Webhook 没有更新。 运行 oratorio server webhook status 和 oratorio server doctor。确认公网 certificate 可信、TCP 80 和 443 已放行、webhook secret 一致，并且 App 订阅了 Issue、Pull Request 和 Issue comment 事件。不要公开 5087。

自动补全中没有 @dotcraft-ai。 请手工输入完整的 @dotcraft-ai review 命令。自动补全和账号通知都不是 Oratorio 接收评论 Webhook 的必要条件。

回写失败。 确认 GitHub writes 已开启，并且 App 拥有本次操作需要的写入权限。

无法创建 Pull Request。 确认 App 可以写入仓库内容、本地 workspace 是同一个 GitHub 仓库的 clone，并且目标分支允许新的 Pull Request。