服务器的 GitHub App

Stamp 通过 GitHub App 访问 GitHub，每个 Raft server 各用自己的一个。这一页写给 server 的 owner 和 admin。还没配过的话，先看管理员上手。

为什么每个 server 都有自己的 App

• 由你们自己掌握。 App 建在你们自己的 GitHub 组织里。装到哪些仓库由你们决定，组织的所有者也能在 GitHub 上管理它。
• 一个 App 只服务一个 server。 别的 server 想用，只能由你们共享过去（见下文）。
• 一个 GitHub 账号一个 App。 每个组织（或个人账号）各用一个私有 App，只能装在它自己的账号上。要在第二个组织里工作，进入 设置 → GitHub App，点「为另一个组织添加 App」。
• 连接 GitHub 也走它。 大家点「连接 GitHub」时，是通过 server 的 App 连接的。有多个 App 时，用的是标着「第一个 App」的那个。

如果你不是那个组织的所有者，GitHub 不会让你在里面创建 App。点「发给该组织的所有者」，填上本 server 里拥有这个组织的人，再点「发送申请」。对方从这条申请里把配置做完。

App 的权限用来做什么

App 只申请 Stamp 真正要用的权限，从不申请 secrets、variables 或 discussions。

• 代码（读写）：推送分支。推送改到 .github/workflows 下的文件时，还需要 workflow（读写）。
• 拉取请求（读写）：开 PR、更新 PR。
• 检查和状态（读写）：写入 check run，以及 Stamp 在提交上的批准状态。
• Actions（读写）：重跑 CI、触发 workflow。
• issue（读写）：agent 创建、评论、编辑 issue，Stamp 的 issue 页面也靠它。
• 分支保护（只读）：合入队列要用。
• 组织成员（只读）。

设置 → GitHub App 里有「GitHub 配置检查」，会把 GitHub 上的 App 和 Stamp 需要的配置逐项对比。标红的项，点「去 GitHub 的 Permissions & events 页修改」，在那边改好。

Stamp 能操作哪些仓库

App 的安装覆盖了哪些仓库，Stamp 就只能操作这些仓库。别的都不在范围内，也没法在 Stamp 里手动添加仓库。

要增减仓库，到 GitHub 上改安装：

1. 打开 设置，找到「仓库访问」，这里列出每个安装和它的仓库。
2. 在对应的安装旁点「在 GitHub 上管理」，在 GitHub 上增减仓库。

改完 Stamp 会自己同步：

• 在 GitHub 上新加的仓库，通常会立刻通知到 Stamp。
• Stamp 每 10 分钟也会自动同步一次。
• 想马上同步，到 设置 → GitHub App 的「同步仓库」这一步，点「刷新仓库列表」。

同步失败时，设置 → GitHub App 会写明原因和该怎么做，已经同步到的仓库不受影响。如果超过一小时都没同步成功，agent 的命令会被拒绝，直到下一次同步成功，所以同步出错要尽快处理。

成员遇到「没有 App」时

只有 owner 和 admin 能配置 App，成员和 agent 可以提申请。

server 还没有 App。 server 既没有自己的 App、也没有别人共享的 App 时，Stamp 会拒绝推送、PR 和评审。登录后看到的是「此 server 尚未配置 GitHub App」：

• owner 或 admin 会看到「新建或关联 GitHub App」按钮。
• 成员会看到「可以联系的 owner 和 admin：」，以及「向管理员申请 GitHub App」按钮。

某个仓库没被覆盖。 agent 会被拒绝，并被提示运行 stamp app request --repo OWNER/REPO。这会提交同一类申请，并写明是哪个仓库。

处理申请

待处理的申请会出现在 设置 → GitHub App 的「待处理的 GitHub App 申请」里。有未处理的申请时，账号菜单里也会出现「GitHub App 申请」入口和数量。每条申请写明是谁、要什么，比如「申请将 OWNER/REPO 加入 App 的访问范围」。

• 把 App 装到那个仓库上（或者配置、共享一个 App）。App 覆盖到之后，Stamp 会自动关闭申请；如果是 agent 提的，它会收到通知。
• 如果是用别的办法解决的，点「标记为已处理」。

这些申请也会显示在申请页面，类型是「服务器的 GitHub App」。

把 App 共享给另一个 server

另一个 Raft server 可以在你选定的安装上使用你们的 App。共享不是独占：你们自己照样在用这些安装。

App 所在的 server 这边：

1. 向对方 server 的 owner 或 admin 要到它的 Server ID。
2. 在 设置 → GitHub App 的「共享给其他 server」里，把它填到「Server ID」，点「查找」。
3. 选「全部安装」（包括以后新增的），或者选「选定的安装」再逐个勾选。
4. 点「共享给 {server}」。对方确认之前显示「待确认」，确认后显示「已生效」。

想调整共享范围，重新共享一次就行；想停止共享，点「撤销」，对方会立刻失去这些仓库。

借用 App 的 server 这边：

1. 在 设置 → GitHub App 的「使用共享的 App」里能看到本 server 的 ID，旁边有「复制」按钮。把它发给对方的管理员。
2. 对方共享后，邀请会出现在这个页面顶部，点「确认关联」或「拒绝」。
3. 确认后，页面会在「关联」下显示这个 App。App 的密钥、webhook 和安装都由对方 server 管理，要调整共享范围请找他们。
4. 不想用了就点「退出关联」，本 server 会立刻失去这些仓库。

一个 server 只能二选一：用自己的 App，或者用别人共享的 App。已经有自己 App 的 server，要先停用自己的 App 才能接受共享；已经关联了别人 App 的 server，要先退出关联才能配置自己的 App。

如果这个 Stamp 部署不允许创建 App，没有 App 时的页面上显示的会是「使用共享的 App」，这时只能通过共享接入。

替换或移除 App

这些操作都在 设置 → GitHub App 的「管理这个 App」里：

• 「替换私钥」：在 App 的 GitHub 页面生成新私钥，填到这里，再去 GitHub 删掉旧私钥。
• 「轮换 webhook secret」：Stamp 生成新 secret 并设置到 GitHub。用旧 secret 签名的事件，在几分钟内仍然有效。
• 「改用另一个 App」：填上另一个 App 的 ID 和私钥，用它替换当前的 App。之后把新 App 装到你们的仓库上。大家需要通过新 App 重新连接 GitHub。

停用某个 App：

• 只有一个 App 时，点「解除关联」，勾选确认框。
• 有多个 App 时，展开那个 App 的卡片，点「从这个服务器移除」，输入账号名确认。如果移除的是「第一个 App」，最早添加的那个会接替它，通过被移除的 App 连接过 GitHub 的人需要重新连接。

不管哪种方式，Stamp 都会立刻停止操作这个 App 的仓库。GitHub 已经发出的 token 最多还有效一小时。Stamp 删不了 GitHub 上的 App：不再需要的话，请到 GitHub 上卸载或删除。