创建 GitHub App

Git 频道与 provider = "github" 会以 GitHub App 身份进行身份验证，而不是以用户身份。该应用拥有自己的机器人身份（your-app[bot]）、自己的权限，并可在其安装到的每个仓库中工作。本页将介绍一次性的应用创建流程，并把每个值映射到频道配置中。

适用于个人账户和组织：唯一的区别在于应用的归属位置以及谁可以安装它。

官方文档： GitHub 自身的 Registering a GitHub App 和 Managing private keys for GitHub Apps 是本页所有内容的上游参考。

1. 创建应用程序

GitHub → 设置 → 开发者设置 → GitHub Apps → 新建 GitHub App.

• **个人应用：**在你的 Developer settings 下创建它。
• Org app: 先切换到该组织（组织中的 Settings → Developer settings），这样该组织就拥有该应用，组织管理员也可以管理它。

填入：

1. 名称 和 主页 URL：任何有效的 URL；该应用从不提供 Web 流量。
2. Webhook → Active：将其取消选中。该频道轮询 REST API；它不会接收 webhook，也不需要公网 URL。
3. 仓库权限：仅授予该 channel 使用的权限，且不多不少：
   • 问题： 读取与写入
   • 拉取请求： 读取和写入
   • 内容： 只读（用于 PR 文件列表和发布）
   • 元数据： 只读（必需；自动选择）
   • 操作： 只读，仅当你路由 workflow_run.* 事件时
   • 将所有其他权限保留为 No access。
4. 此应用可以安装在哪里？：“仅限此帐户”适用于个人或单组织设置。

点击 Create GitHub App。

2. 收集这两项凭据

在应用创建后的设置页面上：

• App ID：显示在顶部附近。这是 app_id。
• 私钥 → 生成私钥。 GitHub 会下载一个单独的 .pem（RS256）。这是你的签名密钥；GitHub 只保留公钥部分。你将其内容粘贴到 private_key；运行时不会引用 .pem 文件本身，因此一旦密钥已存储，你就可以删除下载的文件。

3. 安装应用

App settings → 安装 App → 选择你的账户或组织 → 选择 All repositories 或特定选择。安装才会授予 app 对仓库的访问权限；没有安装，app 可以通过身份验证，但看不到任何内容。

如果应用只安装在一个账号上，你可以不设置 installation_id：该通道在首次使用时会列出安装并自动选择唯一的一个；如果发现没有或有多个，就会快速失败。只有在应用有多个安装时才显式设置 installation_id（一个通道别名只服务于一个安装）。

4. 映射到配置

在您偏好的任意界面上设置以下每个字段。私钥是一个加密的密钥，并会有自己单独的掩码小部件；其余字段都是普通字段。

provider：设置为 github。

zeroclaw config set channels.git.<alias>.provider <value>

app_id：步骤 2 中的 App ID。

zeroclaw config set channels.git.<alias>.app_id <value>

private_key：来自步骤 2 的 PEM。它以内联形式存在于那个加密的配置存储中；磁盘上没有单独的密钥文件需要保护。粘贴完整的 PEM，包括 BEGIN/END 行；仪表板会将其呈现为一个带掩码的多行字段。

channels.git.<alias>.private_key 是机密信息。 以加密形式存储，绝不明文写入 config.toml。通过以下任一方式设置，它们会在写入时加密：

zeroclaw config set channels.git.<alias>.private_key    # 提示输入掩码内容，以加密形式存储

repos：要监视的 owner/repo 列表。留空可轮询安装可见的每个仓库。

zeroclaw config set channels.git.<alias>.repos <value>

installation_id：可选，仅当应用有多个安装实例时（步骤 3）。如果只有一个安装实例，则保持未设置，由频道自动选择。

zeroclaw config set channels.git.<alias>.installation_id <value>

有关完整字段参考，请参阅 Git channel 页面。

5. 验证

Git 通道包含在标准分发构件中，但不包含在精简版 Cargo 默认配置中。对于自定义源码构建，请包含 channel-git（禁用默认特性时还需包含 agent-runtime）：

cargo build --features channel-git

channel-git 会在一次构建中拉入所有已连接的 forge provider；没有更小的按 provider 划分的子集，而且在不包含 channel-git 的情况下构建一个裸的 provider-* feature 不会注册该 channel。

启动时，该 channel 会签发一个 app JWT，将其兑换为 installation token，并解析其自身的 bot 登录名。现在，pull_request.opened 或在 issue 上 @ 提及该 app 应该能够到达 agent。如果启动因缺少 private-key 错误而失败，说明 private_key 未设置或为空；如果因 installation 错误而失败，说明该 app 没有安装或有多个安装，因此请设置 installation_id。有关事件路由、peer-group 绑定和操作说明，请参阅 Git channel 页面。

下一步

• 返回频道： Git channel 用于事件路由、流式传输、速率预算和安全性。
• 限制哪些人可以访问该代理： Peer Groups。
• 从 forge 事件驱动自动化： 标准操作程序 和 Git SOP fan-in。
• 刚接触 ZeroClaw？ 快速入门 和 概念。