> ## 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/ja/account/security)で確認できます。
</ParamField>

このエンドポイントは、Square Cloud GitHub App を通じてアプリケーションを GitHub のリポジトリとブランチに連携し、そのブランチへの push のたびにアプリケーションがデプロイされるようにします。[GitHub Webhook の設定](/ja/api-reference/endpoint/apps/deploy/webhooks) に代わる推奨の方法で、パーソナルアクセストークンは保存されず、各デプロイはコミット上の Check Run として表示されます。

呼び出す前に、GitHub アカウントを Square Cloud に接続し、Square Cloud GitHub App をリポジトリにインストールしてください。リポジトリは、ご自身の GitHub アカウントが保有するインストールの対象になっている必要があります。そうでない場合、リクエストは `REPOSITORY_NOT_AVAILABLE` で失敗します。`apps:deploy` スコープを持つ API キーで利用でき、呼び出せるのはアプリケーションの所有者のみです。

1 つのアプリケーションが持てる GitHub App 連携は一度に 1 つだけです。別のリポジトリを連携する前に、現在のリポジトリを [連携解除](/ja/api-reference/endpoint/apps/deploy/github-app-unlink) してください。また、同じリポジトリとブランチを自分の 2 つのアプリケーションに連携することはできません。連携すると、[現在のデプロイメントの取得](/ja/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>
  push によってアプリケーションをデプロイするブランチです。最大 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  | このリポジトリとブランチは、すでに別のアプリケーションに連携されています。                              |