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

# 关联 GitHub App 仓库

> 通过 Square Cloud GitHub App 将 GitHub 仓库和分支关联到应用。

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  你账户的 API 密钥。你可以在[账户设置](https://squarecloud.app/zh/account/security)中找到它。
</ParamField>

该端点通过 Square Cloud GitHub App 将应用关联到 GitHub 仓库和分支，使每次推送到该分支时都会部署应用。它是[设置 GitHub Webhook](/zh/api-reference/endpoint/apps/deploy/webhooks)的推荐替代方案：不会存储任何个人访问令牌，并且每次部署都会在提交上显示为一个 Check Run。

调用前，请先将你的 GitHub 账户连接到 Square Cloud，并在仓库上安装 Square Cloud GitHub App。该仓库必须包含在你自己的 GitHub 账户所拥有的安装中；否则请求会以 `REPOSITORY_NOT_AVAILABLE` 失败。它支持具有 `apps:deploy` 权限范围的 API 密钥，并且只有应用所有者可以调用。

一个应用同一时间只能有一个 GitHub App 关联，因此在关联其他仓库之前，请先[取消关联](/zh/api-reference/endpoint/apps/deploy/github-app-unlink)当前仓库；同一仓库和分支也不能同时关联到你的两个应用。关联会使[获取当前部署](/zh/api-reference/endpoint/apps/deploy/info)的缓存响应失效。调用频率限制为每个用户每 60 秒 3 次，与取消关联共享该限额。

### 参数

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  应用的 ID。你可以在应用控制台的 URL 中找到它。
</ParamField>

<ParamField body="repositoryName" type="string" placeholder="octocat/hello-world" required>
  仓库的完整名称，格式为 `owner/repository`。
</ParamField>

<ParamField body="repositoryBranch" type="string" placeholder="main" required>
  推送后会部署应用的分支。最多 256 个字符，且必须存在于仓库中。
</ParamField>

### 响应

<ResponseField name="status" type="string">
  指示调用是否成功。成功时为 `success`，否则为 `error`。
</ResponseField>

<ResponseField name="response" type="object">
  响应的内容。

  <Expandable title="展开对象">
    <ResponseField name="repository" type="object">
      关联的仓库。

      <Expandable title="展开对象">
        <ResponseField name="id" type="number">
          仓库的 GitHub ID。
        </ResponseField>

        <ResponseField name="full_name" type="string">
          仓库的完整名称。
        </ResponseField>

        <ResponseField name="branch" type="string">
          部署应用的分支。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={"system"}
  {
      "status": "success",
      "response": {
          "repository": {
              "id": 1234567,
              "full_name": "octocat/hello-world",
              "branch": "main"
          }
      }
  }
  ```
</ResponseExample>

### 常见错误

| 代码                                     | HTTP | 说明                                              |
| -------------------------------------- | ---- | ----------------------------------------------- |
| `MISSING_REQUIRED_FIELDS`              | 400  | 缺少 `repositoryName` 或 `repositoryBranch`。       |
| `INVALID_BRANCH_LENGTH`                | 400  | 分支名称超过 256 个字符。                                 |
| `BRANCH_NOT_FOUND`                     | 400  | 该分支在仓库中不存在。                                     |
| `GIT_ALREADY_CONFIGURED`               | 400  | 该应用已有 GitHub App 仓库。请先取消关联。                     |
| `REPOSITORY_NOT_AVAILABLE`             | 403  | Square Cloud GitHub App 未通过你的 GitHub 账户安装在该仓库上。 |
| `REPOSITORY_NOT_FOUND`                 | 404  | 仓库不存在，或你的 GitHub 账户无法访问它。                       |
| `APP_NOT_FOUND`                        | 404  | 应用不存在，或你不是其所有者。                                 |
| `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | 409  | 你的另一个应用已关联此仓库和分支。                               |