设置 GitHub 集成

本指南介绍设置中与 GitHub 相关的部分。GitHub 是三种受支持的代码托管平台之一——连接 GitLab 或 Bitbucket，以及一个工作区如何混用它们，参见连接代码托管。

前提条件

一个 GitHub 账号，且能访问你想处理的仓库
要么为你的服务器注册一个 GitHub App（参见创建 GitHub App），以便你登录；要么准备一个带 repo 和 read:org 权限、可供粘贴的个人访问令牌

使用 GitHub 登录

这是一种设备流程：GitHub 向你显示一个短代码，你在 github.com 上批准它，服务器随即收到凭据——不需要回调 URL，不需要端口，也没有任何东西需要对外暴露。只要服务器有 client id 就可用，而官方构建已经自带。

前往 设置 → 工作区 → 个人资料与身份 → 代码托管（或入门流程的第一步）
在 GitHub 行上，点击 使用 GitHub 登录
对话框会显示一个由八个字符组成的代码，并在你的浏览器中打开 github.com/login/device。该代码已经复制到你的剪贴板
粘贴代码，批准该应用，然后返回。该行会自动变为 “已以 your-username 身份登录”

你可以在浏览器中继续操作的同时关闭该对话框——服务器会持续轮询，直到代码过期（约 15 分钟），所以登录仍然会完成。

或粘贴令牌

当服务器没有 App、App 未安装在你要用的账号上，或者你干脆更想使用 PAT 时，这是后备方案。

前往 设置 → 工作区 → 个人资料与身份 → 代码托管
在 GitHub 行上，点击 添加令牌
粘贴一个带 repo 和 read:org 权限的令牌（经典）并保存。细粒度 令牌需要仓库的 Contents 和 Pull requests（读和写）权限，外加 Checks 和 Actions（读）权限。

令牌在保存时就会被探测，因此该行能指出它属于哪个账号。点击断开连接即可移除它。

检查点：GitHub 行显示“已以 your-username 身份登录”。如果应答的凭据不是你的，末尾会标出来源——“通过此服务器的应用”或“来自环境”。

集成为你提供什么

功能	实现方式
PR 列表与详情	通过服务器调用 GitHub REST API，使用 App 身份或你自己的凭据
检查运行	GitHub Checks API
发布审查	一个需要用户确认的步骤，会把你的审查发布到 PR 上
仓库注册	只要检出副本的 `origin` 远程指向 github.com——或指向 gitlab.com / bitbucket.org，就会被接受
智能体的 GitHub 访问	凭据代理会把只读令牌以 `GH_TOKEN` / `GITHUB_TOKEN` 注入；推送经由 Control Center
通知提醒	服务器端轮询你的 GitHub 通知收件箱，触发“在 pull request 中被提及”和“已请求评审”
用户资料	资料悬浮卡片，以及按作者筛选 PR

在更划算的地方，某些路径会改用 GraphQL API 而不是 REST——例如撰写 PR 时选择器所需的分支活动，以及用来判断某条“已请求评审”通知是否仍处于待处理状态的实时审查状态。

留意 GitHub 服务中断

当某个提供方降级时，标题栏会显示一个状态标签，涵盖 GitHub、Claude、OpenAI 和 Kimi。一切正常时它是隐藏的——它的出现是在报告问题，而不是报告没有问题。

点击该标签会打开一个浮出面板，其中列出每个提供方的状态，并带有一个刷新按钮。这些状态每两分钟会自动刷新一次。

了解智能体在 GitHub 上的行为

在 GitHub 工作树中工作的智能体始终拿到只读的 GitHub 令牌。推送会经由 Control Center，它先询问推送到远程仓库规则，再用一个智能体从不持有的写入令牌转发推送。参见配置沙盒策略
智能体创建的提交以智能体的身份署名——显示名称加上 (agent)，地址是由智能体 id 派生的合成地址——绝不会作为人来署名。发起请求的人则通过 Co-Authored-By 尾注记入贡献
配置了 GitHub App 后，代理会在每次运行时签发细粒度、限定到仓库、有效期约一小时的安装令牌，而不是交出一个权限宽泛的令牌。安装实例根据该次运行的仓库所有者来解析，因此一个 App 装在多个账号上时，会正确限定到该次运行所触及的那个账号。没有 App 时，智能体收到的是环境令牌，它无法收窄为只读：此时推送规则能约束 git push，但约束不了直接使用该令牌的代码
令牌始终是代理的，绝不是发起请求的成员自己的。对于代表一位既不是所有者、又没有连接 GitHub 的成员行事的运行，服务器令牌会被扣留

故障排查

PR 列表为空，并提示 GitHub 未连接

你在这台服务器上没有任何 GitHub 凭据。请在代码托管下登录或粘贴令牌。其他托管平台上的仓库不受影响——只有 GitHub 的仓库不会贡献任何内容。

该行只提供“添加令牌”，没有“使用 GitHub 登录”

服务器没有 client id——这是从源码构建的常规状态，因为凭据只会烘焙进官方构建中。参见创建 GitHub App：大约只需两分钟，而且只有服务器所有者需要做，做一次即可。

登录对话框提示提供方未返回设备代码

GitHub App 存在，但其 Device flow 复选框处于关闭状态。在该应用的设置中（General → Device flow）将它打开，然后重试。

该行显示“通过此服务器的应用”，但我预期的是自己的账号

你尚未登录；你看到的是服务器的 App 身份在应答。请在该行点击 使用 GitHub 登录。

细粒度 PAT 不显示合并按钮或检查状态

该令牌需要 Contents 和 Pull requests（读和写）权限，外加 Checks 和 Actions（读）权限。更改之后，请在代码托管下重新粘贴。

添加仓库被拒绝

注册需要同时满足以下三项：该路径位于一个 git 工作树内、它有一个 origin 远程，并且该远程指向受支持的托管平台（github.com、gitlab.com 或 bitbucket.org）。参见向工作区添加仓库。

重度使用后一切会停止工作一段时间

那是限流熔断器。GitHub 用带有 x-ratelimit-remaining: 0 的 403 以及重置时间来表示它的主要限流；客户端一旦看到，就会在窗口期结束前不再发起网络调用、直接在本地让后续请求失败，因此重试风暴无法加深限流。瞬时故障会以指数退避最多重试三次，并遵循 retry-after。