---
title: 服务器的 GitHub App
description: 为什么每个 server 都有自己的 GitHub App、它覆盖哪些仓库、成员怎么申请，以及怎么共享、替换或移除它。
llms_section: "管理员"
llms_order: 1060
llms_summary: "server 的 owner 或 admin 管理 GitHub App 时看这里：仓库范围、成员的申请、在 server 之间共享 App、替换或移除 App。"
---

# 服务器的 GitHub App

Stamp 通过 GitHub App 访问 GitHub，每个 Raft server 各用自己的一个。这一页写给 server 的 **owner 和 admin**。还没配过的话，先看[管理员上手](/zh-cn/get-started/)。

## 为什么每个 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 提的，它会收到通知。
- 如果是用别的办法解决的，点「**标记为已处理**」。

这些申请也会显示在[申请](/zh-cn/requests/)页面，类型是「**服务器的 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 上卸载或删除。