> ## Documentation Index
> Fetch the complete documentation index at: https://cloud-docs.orbi.build/llms.txt
> Use this file to discover all available pages before exploring further.

# 连接仓库

> 我怎么把一个仓库连到 Orbi Cloud，之后又怎么换掉它?

连接仓库是告诉 Orbi 它可以处理哪个仓库的 Issue，以及往哪个分支提交拉取请求。

Orbi Cloud **同一时间只在一个生效的仓库里**工作。连接是自助的：你在连接页上挑好仓库和基础分支，开通随即开始。

## 连接

在状态页上点 **连接仓库** (Connect repository)（或者**绑定的仓库** (Connected repository) 卡片里的 **更换仓库** (Connect / change repository)）。

<Frame caption="连接仓库页，显示仓库和基础分支两个下拉">
  <img src="https://mintcdn.com/orbi-cloud/Ya1dzVX1ins06kld/images/zh/connect.png?fit=max&auto=format&n=Ya1dzVX1ins06kld&q=85&s=535ad508f23a71f3603169f8ffdf1fd4" alt="连接仓库页，显示仓库和基础分支两个下拉" width="1920" height="1476" data-path="images/zh/connect.png" />
</Frame>

1. **Repository** —— 从你的 GitHub App 安装所覆盖的仓库里挑。
2. **Base branch** —— Orbi 提交拉取请求的目标分支。选中一个仓库之后，页面会载入它真实的分支列表并预选默认分支，所以通常你只需要确认。
3. 点 **连接仓库**。

你会回到状态页，**绑定的仓库**卡片这时列出了这个仓库，带一个 **生效中** (Active) 标记，开通开始。

## 仓库要满足的条件

一个仓库只有在下面两条都成立时才能被连接：

* 它**在你的 GitHub App 安装范围内**。Orbi 只看得见你授权过的仓库。
* 它**开启了 Issues**。Orbi 的输入渠道全部是 Issue，所以关掉了 Issues 的仓库会被拒掉。

这两条在你提交时都会重新检查，不只是在页面渲染时查一次 —— 所以中间被取消授权的仓库也会被拦住。

## 列表里没有你的仓库时

下拉里只有你的 App 安装覆盖到的仓库。如果你的不在里面，展开连接页上的 **没找到你的仓库？** (Cannot find your repository?)：它会说明原因，并给出指向 GitHub App 设置的链接，你可以在那里把仓库加进安装范围。

你也可以在任一个下拉里用 **手动填写** (Enter manually) 直接输入一个 `OWNER/REPO` 值。这在列表暂时读不出来的时候有用，但它不会绕过授权检查 —— App 访问不到的仓库在提交时照样会被拒掉。

<Frame caption="连接页的降级状态，有手动填写字段和一条说明原因的文字">
  <img src="https://mintcdn.com/orbi-cloud/Ya1dzVX1ins06kld/images/zh/connect-degraded.png?fit=max&auto=format&n=Ya1dzVX1ins06kld&q=85&s=9ea2b397ae6ca668fff9149d1e8c232e" alt="连接页的降级状态，有手动填写字段和一条说明原因的文字" width="1920" height="1724" data-path="images/zh/connect-degraded.png" />
</Frame>

如果 GitHub 的仓库列表完全读不出来，页面会降级成手动填写并告诉你原因，而不是把你堵在那里。

## 会卡住每一次合并的分支保护

如果你的基础分支要求合并前必须有批准评审，连接页会立刻用红色警告你，因为这个设置会让**每一次**交付都停在合并那一步。

原因在身份：Orbi 用同一个 GitHub App 的身份提交拉取请求并合并它，而 GitHub 不允许一个拉取请求的作者批准自己的拉取请求。在必须批准的规则生效时，每次交付都只能走到「评审过、可以合了」这一步，然后合不进去。

有三种解法 —— 按你的策略挑一个：

1. **每次交付你自己批准**。你或者同事在拉取请求上点 **Approve**，合并就继续。每一个改动都保留人在环里。
2. **让 admin 可以绕过**。在 **Settings → Branches → Branch protection rules**（或者 **Settings → Rules → Rulesets**）下面开启 **Allow admins to bypass**，或者把这个账号加进 ruleset 的 bypass 列表。
3. **把必须批准数设成 0**，同一处设置里改。

改完不需要重新连接 —— 下一次交付的拉取请求就能正常合并。

## 更换绑定的仓库

用 **更换仓库**，连一个别的。新仓库变成生效状态，前一个转入历史 —— 它不会被删掉，在状态页的**历史仓库** (Historical repositories) 里还能看到。

换仓库会为新的那个重新开通一个环境，同样需要一两分钟。

<Note>
  有交付正在执行时你换不了仓库。页面会告诉你**仍有交付在进行中**，请你稍后再试。这是在保护那次正在跑的交付 —— 等它走到 `ai-merged` 或 `ai-blocked`，再换绑。
</Note>

## 各种报错是什么意思

| 页面上写的                     | 发生了什么                | 怎么办                                            |
| ------------------------- | -------------------- | ---------------------------------------------- |
| 这个仓库没有授权给 Orbi GitHub App | 仓库在你的安装范围之外          | 打开安装设置，把仓库加进去，刷新连接页                            |
| Issues 已关闭                | 仓库关掉了 Issues 功能      | 在仓库的 **Settings → Features → Issues** 里打开，然后重试 |
| 仍有交付在进行中                  | 当前绑定的仓库里有交付在跑        | 等它结束，再换绑                                       |
| 仓库列表暂时不可用                 | GitHub 的 API 连不上     | 重试；一直不行就用手动填写                                  |
| 仓库格式不合法                   | 手动填的值不是 `OWNER/REPO` | 按 `owner/repository` 重填，例如 `orbi-build/orbi`   |

## 接下来会发生什么

连接会触发[开通](/zh/provisioning) —— Orbi 搭起你的交付所运行的隔离环境，并把 `ai-*` 标签装进你的仓库。盯着**开通状态** (Provisioning status) 那一列，直到它显示**开通成功** (Provisioned)，然后[建你的第一张 Issue](/zh/first-issue)。