连接代码托管

Control Center 可与三种代码托管服务配合使用，应用内统称代码托管平台：GitHub、GitLab 和 Bitbucket Cloud。它们中没有哪一种是默认选项。连接其中一个，一切即可正常工作；连接多个，单个工作区也能同时容纳来自所有这些平台的仓库。

代码托管平台是每个仓库的属性，在你注册仓库时从其 origin 远端读取。你从不需要自行选择，也不存在会设置错的按工作区配置。

连接代码托管平台

打开 设置 → 工作区 → 个人资料与身份（/settings/workspace/profile）。
找到 代码托管 卡片。所有受支持的代码托管平台都会列出，无论是否已连接。
如果该行提供 使用 … 登录，就按下它；否则按下 添加令牌 并粘贴一个令牌。

登录只会在你的服务器已为其注册应用的代码托管平台上出现 —— 目前是 GitHub，通过设备流完成（参见创建 GitHub App）。其他平台都是粘贴令牌，这是一项诚实可用的操作，而不是一个无法完成的按钮。

无论哪种方式，凭据都是你自己的，并且保存在服务器上，以你的用户 ID 为键：你输入令牌的那台机器上不会存储任何令牌，你登录的每台设备使用的都是同一个凭据，其他成员也无法读取它。它会在下一次请求时生效 —— 没有任何东西需要重启，而断开连接后它立刻不再被发送。

每一行都会告诉你它的凭据来自哪里，因为这正是“我的令牌不起作用”与“另一个令牌在应答”之间的区别：

副标题	含义
`已以 octocat 身份登录`	正在使用你自己的凭据
`已以 octocat 身份登录 · 通过此服务器的应用`	服务器的应用身份正在应答 —— 你尚未登录
`已以 octocat 身份登录 · 来自环境`	服务器的环境变量正在应答，而不是你的凭据
`未连接`	你在此代码托管平台上没有任何凭据

每种代码托管平台需要哪种令牌

代码托管平台	令牌	创建位置
GitHub	经典：`repo` 和 `read:org`。细粒度：Contents + Pull requests (read/write)、Checks + Actions (read)	github.com → Settings → Developer settings → Tokens
GitLab	带有 `api` 的个人访问令牌	gitlab.com → User settings → Access tokens
Bitbucket	一个 Atlassian API 令牌，外加你的账户邮箱	id.atlassian.com → Security → API tokens

Bitbucket 使用你的账户邮箱作为用户名、令牌作为密码进行身份验证。在服务器环境中设置 BITBUCKET_EMAIL，它才知道该把哪个邮箱与令牌配对。

或者使用环境变量

对于无界面或 CI 安装，服务器会读取以下变量：

GitHub —— GITHUB_TOKEN，然后是 GH_TOKEN
GitLab —— GITLAB_TOKEN，然后是 CI_JOB_TOKEN
Bitbucket —— BITBUCKET_API_TOKEN，然后是 BITBUCKET_TOKEN（配合 BITBUCKET_EMAIL）

这些是服务器的凭据，而不是你的，而这个区分至关重要：以你的名义发起的请求只会使用你的凭据，不会用别的，因此环境绝不会悄悄代替你。没有人在其后的工作 —— webhook、PR 轮询、工单同步 —— 会先解析服务器的应用身份，然后是服务器所有者的凭据，最后才是环境。这个顺序是固定的，因此“我登录了却什么都没变”永远不可能是受支持的结果。

在每个代码托管平台上，你是不同的人

同一个人，在 GitHub 上是 octocat，在 GitLab 上则完全是另一个身份。Control Center 会按代码托管平台解析你的身份，并为每个仓库使用正确的那一个 —— 正是这一点，让“需要我审查”“由我创建”和“你已批准”在混合工作区中保持正确。

如果某个代码托管平台的身份尚未解析，它的仓库不会向收件箱贡献任何内容，而不是匹配所有内容。收件箱会如实说明这一点，而不是声称你已全部处理完毕。

一个收件箱，涵盖所有代码托管平台

收件箱和 PR 队列会向工作区中出现的每个代码托管平台分发查询，并把结果合并成一条流 —— 一个 GitHub pull request 和一个 Bitbucket pull request 彼此相邻，按时间排序，而不是按供应商分组。

故障是相互隔离的。一个宕机、被限流或未连接的代码托管平台不会贡献任何内容，也不会影响其他平台；它绝不会清空整个收件箱。它自己的仓库会继续显示最后已知的状态，直到它恢复。

每种代码托管平台能做什么

每种代码托管平台都支持核心循环：列出并打开 pull request、读取 diff、进行行内评论和顶层评论、审查、合并和关闭。在此之外，它们确实各不相同，而 Control Center 会隐藏某个代码托管平台做不到的功能，而不是显示一个会静默失败的控件。

能力	GitHub	GitLab	Bitbucket
批量（待提交）审查	✓	✓	—
请求变更	✓	✓	✓
按文件同步“已查看”状态	✓	—	—
Emoji 表情回应	✓	✓	—
团队 / 群组审查者	✓	✓	—
建议的审查者	✓	—	✓
PR 上的 CI 结果	✓	✓	✓
深入查看 CI 任务的步骤/日志	✓	✓	—
堆叠的 pull request	✓	—	—
PR 描述模板	✓	✓	—
通知轮询	✓	—	—
丰富的用户资料	✓	✓	—
服务器端 PR head ref	✓	✓	—

当某项能力缺失时，相关功能的降级是诚实的：

已查看状态仍然可用，但只在你设置它的那台设备上生效。
Bitbucket 上的批量审查会一条评论一条评论地发布，因此审查者看到它们逐条到达，而不是一次性全部出现。
Bitbucket 上没有 PR head ref 意味着检出 pull request 时会按名称获取其源分支，而一旦该分支被删除，这就会失败。

术语

GitLab 把 pull request 称为 merge request。Control Center 在自己的模型中始终说“pull request”，而在谈论某个代码托管平台本身时，会使用该平台自己的说法。

故障排查

PR 列表为空，并提示某个代码托管平台未连接

你没有该代码托管平台的凭据。请在 设置 → 工作区 → 个人资料与身份 → 代码托管 中登录或粘贴令牌。其他代码托管平台的仓库不受影响。

我连接了代码托管平台，但它的仓库仍然什么都不显示

检查该行的副标题。如果显示的是“通过此服务器的应用”或“来自环境”，那么正在应答的凭据与你预期的不一样 —— 对于你发起的任何请求，你自己的凭据都会优先，所以如果显示的是别的，说明你的凭据没有被保存。

仓库无法注册

注册需要同时满足三个条件：路径位于 git 工作树内、它有一个 origin 远端，并且该远端指向 github.com、gitlab.com 或 bitbucket.org。参见向工作区添加仓库。

大量使用之后，一切会停摆一段时间

那是速率限制断路器。当某个代码托管平台发出达到主限制的信号时，客户端会在本地让后续请求失败，不发起网络调用，直到时间窗口过去 —— 这样重试风暴就无法加深限制。瞬时故障会以指数退避重试。

连接代码托管