GitHub

GitHub 集成让 Agent 监视一个仓库，或某个安装实例下的全部仓库：新的 Issue、Pull Request 和评论会成为会话，Agent 则可以用 PR / Issue 评论的形式回写。它依托部署的 AgentConnect GitHub App。AgentConnect Cloud 不需要为每个仓库配置 Webhook；AgentConnect OSS 的运维人员则在 Relay 上配置一个部署级别的 GitHub App Webhook。

监视仓库复制锚点链接

在 Agent 页面：集成 → 添加集成 → GitHub。

1. 仓库——从 GitHub App 覆盖、且当前登录者有权使用的仓库中选择。公开仓库始终可用于只读设置；私有仓库需要一个已关联且具备访问权限的 GitHub 身份。如果选中的仓库尚未授权给该 Agent，授权步骤会直接在此处打开。列表以每个 GitHub App 安装实例开头，显示为整个 <account>（见下文）。

2. 监听对象——Pull Request、Issue、部署、Release，或任意组合；每一项都有自己的触发器。

3. 触发条件——Agent 被唤醒的积极程度：

   • 创建时——当 PR 或 Issue 被创建时，以及之后在所选类型中被明确提及时。
   • 任意更新——创建，加上受支持的新修订、标签和回复。关闭、重新打开和正文编辑不会运行 Agent。
   • @ 提及——当被分配的 Agent 或 GitHub App 被 @ 提及时。以原生方式请求该 App 作为 PR 评审者同样属于明确请求，可以启动匹配的 PR 评审者。

   部署和 Release 没有可供提及的线程。当部署被创建或报告任意状态时，以及当 Release 已发布或有任意更新（每次发布、编辑或取消发布）时，Agent 都会运行。

当多个 Agent 关注同一个仓库时，在 Issue 或 Pull Request 行上选择添加决策，就能由决策挑选由哪些 Agent 接手每一个。

监视安装实例下的全部仓库复制锚点链接

选择整个 <account> 会监视该安装实例覆盖的每一个仓库，包括之后再加入的仓库。你监听的每个对象会成为一个名为 <account>/* 的监视项，各自拥有自己的触发节奏和评审设置。

• 这需要 Agent 的安装实例授权，只有组织所有者才能授予。缺少该授权时，所有者会被带到该步骤；其他人则可以在授权完成后选择该安装实例。
• 正式评审和信息性 Check 需要该授权处于读写级别。各个仓库不需要单独授权，即使是 Check 也不需要。
• 在同一个仓库上，同一个 Agent 针对该仓库和对象的单独监视项优先，因此 Agent 绝不会因为一个事件运行两次。想给某个仓库不同的设置，就用单独的监视项。
• 要把某个仓库排除在外，把它从 GitHub App 安装实例中移除，或者改为逐个仓库监视。
• 只要 Agent 仍持有针对整个安装实例的监视项，该安装实例授权就无法撤销。请先删除这些监视项。

谁可以触发 Agent复制锚点链接

AgentConnect 通过 GitHub 检查内容作者的当前仓库权限。只有拥有 triage、write 或 admin 权限（Maintain 按 write 计）的人，或在该仓库受信任用户列表中的人，才能自动启动 Agent；GitHub Webhook 中的 author_association 标签不被视为权威依据。

• 达不到上述要求的人创建的 Issue 或 Pull Request 不会启动 Agent，即使正文中提及了该 Agent 或 GitHub App。
• 当前维护者或受信任用户可以在评论中明确提及该 Agent 或 App，以在外部作者创建的线程上请求第一轮工作。达不到触发要求的人发出同样的提及不会启动任何工作：App 会在该线程里回复一次固定说明，告诉对方可以请维护者提及该 Agent 来处理。
• 未提及 Agent 的后续回复只有在评论者和原 Issue / PR 作者都仍满足上述要求时，才按配置的触发节奏处理。
• 原生的评审请求和 Check 重跑遵循同样的“当前维护者”边界。

AgentConnect 检查每条评论（包括被编辑的内容）的作者；不会用 Webhook 的发送者替代内容作者。触发权限与 Agent 之后能做什么是两回事：评论、正式评审、Check 和仓库写入仍然需要已配置的 AgentConnect 仓库授权和 GitHub App 权限。

关联到已登录 AgentConnect 个人资料的 GitHub 身份可以参与两项彼此独立的控制台用户检查：

• 可选的按用户仓库授权用它来验证私有仓库访问权限和每一项写入授权；以及
• 设置 → 会话访问权限 → 要求 GitHub 访问权限在判断查看者是否可以读取来自私有仓库的会话时会用到它。

公开仓库的只读设置和公开仓库的会话不需要关联 GitHub 个人资料。关联 GitHub 不会安装 GitHub App、不会授予仓库，也不会改变上述 Webhook 作者规则。参见关联账号。

受信任用户复制锚点链接

要让达不到上述要求的人也能启动 Agent，比如外部贡献者或只有读权限的同事，在 Pull Request 或 Issue 监视项的设置（⋯ → Settings…）里，把他们的 GitHub 用户名加到受信任用户中。修改这个列表需要该 Agent 的编辑权限。

• 这个列表属于仓库：该仓库的每个监视项，不论属于哪个 Agent、监听哪类对象，读取的都是同一份。受信任用户通过上述每一项检查，和维护者完全一样：作为评论者、作为 Issue 或 Pull Request 的作者，以及在未提及 Agent 的后续回复中。
• AgentConnect 通过该仓库自己的 App 凭证，把用户名解析成账号的数字 ID，并按这个 ID 匹配。无法解析的用户名在添加时就会被拒绝；之后改名或被他人重用的用户名也不会让其他人获得信任。
• 针对整个安装实例的监视项没有自己的列表。它读取的是每个事件所在仓库的列表，而这份列表只能在该仓库的监视项里编辑，所以它的设置里不提供这一项。

Agent 会做什么复制锚点链接

每个符合条件的事件都会在 Agent 的 Daemon 上启动一个会话，并以该事件作为上下文（标题、正文，以及适用时的 diff 摘录）。即使工作区为只读，已启用的监视项也可以发布 Agent 的普通最终回复。正式评审、状态 Check 和仓库变更需要读写授权。参见工作区与仓库。

由 GitHub 触发的会话会出现在会话中，以仓库 / 线程作为其频道，并链接回 GitHub。启用仓库访问同步后，它们的只读 GitHub 成员受众跟随源仓库当前的可见性和查看者的访问权限，而不是 AgentConnect 的角色覆盖。

PR 评审复制锚点链接

对于 Pull Request 监视项，展开 PR 评审并选择：

• 关闭——运行 Agent 并把最终回复作为普通 PR 评论发布，不做正式评审或 Check。
• 简要——允许正式的 COMMENT 评审和行内评论。
• 详细——展示行内评论、REQUEST_CHANGES、APPROVE 和信息性状态 Check 的控制项。

正式评审需要 Agent 拥有仓库写入权限，以及有效的 GitHub App pull_requests:write 权限。信息性 Check 还额外需要 checks:write。

多个 Agent 可以监视同一个仓库。在 PR 对话中，@<agent-name> 指向一个匹配的 Agent，而 @<github-app-name> 会广播给所有匹配的评审者。两种形式都仍然遵循事件类型、标签、安装实例、实时维护者授权和机器人发送者安全检查。

当 PR 无法自动启动时——最常见的原因是其作者不是当前维护者——已启用的状态 Check 可以提供请求评审操作。当前维护者可以用它启动评审，而无需添加评论。

完整的双模型配置见快速 PR 评审与按需深度评审。

合并前要求评审复制锚点链接

AgentConnect 本身从不阻止合并。要让合并等待某个评审者，请在目标分支的 ruleset 或分支保护中要求其信息性 Check：

1. 为该评审者设置一个 Pull Request 监视项，触发节奏为任意更新，且仅包含这些标签下不填任何内容，并在 PR 评审 → 详细下开启其信息性 Check。Check 只会出现在该监视项评审过的修订上，因此换成其他任何设置，都会有一些 Pull Request 永远等待下去。
2. 在 GitHub 中启用 Require status checks to pass，并添加 AgentConnect PR Review: <agent-name>。把它的来源设为 AgentConnect GitHub App，这样其他任何东西都无法满足该检查。

此后，在评审排队或运行中、Agent 请求修改时，以及评审失败或从未运行时，合并都会被阻止。它不是一个批准门槛：

• 只带评论结束的评审报告为 neutral，GitHub 将其视为通过。
• 在没有新提交的情况下更改目标分支会保留 head 的 Check，因此在新评审发布自己的结果之前，之前的结果仍然有效。

要从失败或被中断的评审中恢复，请在 Pull Request 的 Checks 标签页使用 Re-run，或使用该 Check 的请求评审操作。作者达不到触发要求、又不是受信任用户的 Pull Request 会一直等待，直到维护者启动评审（谁可以触发 Agent）。

让 Agent 名称支持自动补全复制锚点链接

在 GitHub 的评论框中输入 @ 时会提示组织的团队，但它没有办法提示 Agent 名称。在组织中创建一个名称与 Agent 完全一致的团队，@<organization>/<agent-name> 就会成为一个提示项，指向同一个 Agent：

1. 在组织中，Teams → New team。
2. 名称与 Agent 名称完全一致——是 review-bot，而不是“Review Bot”。
3. 可见性保持 Visible。秘密团队不会出现在评论框中。
4. 写一段类似“AgentConnect Agent shortcut”的描述，告诉队友这个条目是干什么用的。

团队不需要任何成员：AgentConnect 匹配的是你输入的文本，从不看团队成员。其他一切都不变——同样的事件、标签、授权和安全检查照常适用，而且不管团队存在与否，普通的 @<agent-name> 都继续有效。

AgentConnect 从不创建、重命名或删除这些团队；它们由你自己管理。团队只存在于组织中，因此在个人账号拥有的仓库上只能使用 @<agent-name>。

给 Agent 单独的 GitHub App复制锚点链接

每个 Agent 一开始都使用部署的内置 GitHub App。使用它的所有 Agent 在 GitHub 上是同一个身份，而 GitHub 不接受 Pull Request 作者对自己的评审，所以评审 Agent 无法批准另一个 Agent 开的 Pull Request，也无法对它请求修改。给评审 Agent 一个单独的 App，它就成了另一个身份。

1. 在 Agent 的 GitHub 卡片上选择 GitHub App。在编辑工作区中，同一个对话框位于 GitHub App 已连接旁的 ⋯ → 使用独立的 GitHub App…。
2. 选一个 AgentConnect 组织里空闲的 App，或选择新建 GitHub App…。列表中的 App 图标可以帮助区分不同身份。
3. 新建时选择 App 归属：我的 GitHub 个人账号，或点击从我的 GitHub 组织中选择，授权现有的内置 GitHub App，加载它可见的账号。请选择你有权管理 GitHub App 的组织。也可以选择手动输入其他组织…，填写 GitHub 组织名。
4. 点击在 GitHub 上继续。AgentConnect 会填好 App 的权限、事件和 Webhook；GitHub 会检查你能否在所选账号下创建 App。确认创建后，把它安装到需要的账号并选择仓库。
5. 回到 AgentConnect 后，对话框会检查该 App 是否覆盖了 Agent 用到的一切：工作区仓库、已授权的仓库和安装实例，以及它监视的仓库。缺少的项会列出来并附带去 GitHub 添加。在 GitHub 上补上后，点击重新检查。
6. 全部覆盖后，选择切换。

截图使用示例账号和 App 图标。App 归属是拥有 App 注册信息的 GitHub 账号，与安装 App 的账号相互独立。新 App 默认是 public，便于后续安装到其他账号。公开 App 不会把仓库变成公开仓库，也不会自动授予仓库访问权限；每次安装都需要单独授权。参见 GitHub App 可见性。

此后 Agent 的一切都通过该 App 进行——事件、仓库凭证、评审和 Check——它的 GitHub 卡片会显示通过 <app-slug>。@<app-slug> 只会叫到这个 Agent。组织中任一 App 开的 Pull Request 仍算作内部 Pull Request，所以使用不同 App 的 Agent 会自动评审彼此的 Pull Request。

一个 App 同一时间只服务一个 Agent。把 Agent 改回内置 App，或删除该 Agent，它的 App 就会空闲出来，供其他 Agent 使用。

组织的 App 列在集成 → 代码托管平台 → GitHub 中内置 App 的下方，并标出使用它的 Agent。展开一个 App 可以看到它安装在哪些账号上。所有者可以在那里把它从某个账号卸载，或删除空闲的 App；删除后的 App 仍留在 GitHub 上，直到你在 GitHub 上也删除它。

找不到自己的组织复制锚点链接

账号列表只包含现有内置 GitHub App 可见的组织，不一定包含你加入的所有组织。仅在个人资料中关联 GitHub 不会授予这项访问权限，也不需要另建 OAuth App。

• 组织未列出时，可以选择手动输入其他组织…。GitHub 仍会检查你的创建权限；手动输入不会授予权限。
• 要让已安装的组织出现在列表中，内置 App 需要 Organization permissions → Members: Read-only，且组织所有者需要为现有安装批准该权限。自托管运维人员可参见更新现有 GitHub App。
• 批准后点击刷新 GitHub 账号列表。如果授权窗口被拦截，请允许控制台打开弹窗后重试。

暂不批准 Members 更新时，安装保留原有权限。现有仓库访问、PR/Issue 操作和 Webhook 投递仍在原权限范围内工作，但组织列表可能不完整。

把同一个 App 安装到其他账号复制锚点链接

打开该 App 在 GitHub 上的公开页面，选择 Install；也可以访问 https://github.com/apps/APP-SLUG/installations/new，把 APP-SLUG 替换为自己的 App slug。选择新增的账号和仓库，并完成所需的组织所有者批准。覆盖检查中的去 GitHub 添加也会打开这一安装流程。

已有安装的设置页只管理该安装的仓库访问范围，不能在那里增加另一个组织。如果较早创建的 App 是 private，App 所有者需要先将可见性改为 public，其他账号才能安装。完成 App 切换前，回到 AgentConnect 点击重新检查。

管理监视项复制锚点链接

Agent 页面把它的 GitHub 集成归为一张卡片——每个被监视的仓库一行，安装实例则显示为 <account>/*，其中包含：

• 事件开关和触发节奏选择器（创建时 / 任意更新 / @ 提及；部署为创建 / 任意状态，Release 为已发布 / 任意更新），
• 最近的投递（触发了什么、何时触发、启动了哪个会话），
• 添加仓库，用同一个 Agent 监视更多仓库。

前提条件复制锚点链接

• GitHub App 必须已为你的组织安装（集成 → 代码托管平台 → GitHub → 在 GitHub 安装）；如果尚未安装，集成对话框会提供安装按钮，并带有已安装，立即同步刷新按钮。
• 已启用的监视项在只读访问权限下可以发布普通的最终回复。正式评审、Check 和仓库变更需要读写。
• 在 AgentConnect OSS 上，运维人员必须先配置部署的 GitHub App 及其 Relay Webhook。