> ## 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.

# Link GitHub App Repository

> Link a GitHub repository and branch to an application through the Square Cloud GitHub App.

<ParamField header="Authorization" type="string" placeholder="API Key" required>
  The API key for your account. You can find this in your [account settings](https://squarecloud.app/en/account/security).
</ParamField>

This endpoint links an application to a GitHub repository and branch through the Square Cloud GitHub App, so every push to that branch deploys the application. It is the recommended alternative to [Set GitHub Webhook](/en/api-reference/endpoint/apps/deploy/webhooks): no personal access token is stored, and each deploy shows up as a Check Run on the commit.

Before calling it, connect your GitHub account to Square Cloud and install the Square Cloud GitHub App on the repository. The repository must be covered by an installation your own GitHub account holds; otherwise the request fails with `REPOSITORY_NOT_AVAILABLE`. It works with an API key that has the `apps:deploy` scope, and only the application owner can call it.

An application holds one GitHub App link at a time, so [unlink](/en/api-reference/endpoint/apps/deploy/github-app-unlink) the current repository before linking a different one, and the same repository and branch cannot be linked to two of your applications. Linking invalidates the cached response from [Get Current Deployment](/en/api-reference/endpoint/apps/deploy/info). Calls are rate limited to 3 per 60 seconds per user, shared with unlinking.

### Parameters

<ParamField path="app_id" type="string" placeholder="Application ID" required>
  The ID of the application. You can find this in the URL of your application's dashboard.
</ParamField>

<ParamField body="repositoryName" type="string" placeholder="octocat/hello-world" required>
  The full name of the repository, in the `owner/repository` format.
</ParamField>

<ParamField body="repositoryBranch" type="string" placeholder="main" required>
  The branch whose pushes deploy the application. Up to 256 characters, and it must exist in the repository.
</ParamField>

### Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful.. `success` if successful, `error` if not.
</ResponseField>

<ResponseField name="response" type="object">
  The contents of the response.

  <Expandable title="Toggle object">
    <ResponseField name="repository" type="object">
      The linked repository.

      <Expandable title="Toggle object">
        <ResponseField name="id" type="number">
          The GitHub ID of the repository.
        </ResponseField>

        <ResponseField name="full_name" type="string">
          The full name of the repository.
        </ResponseField>

        <ResponseField name="branch" type="string">
          The branch that deploys the application.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

### Common errors

| Code                                   | HTTP | Meaning                                                                                     |
| -------------------------------------- | ---- | ------------------------------------------------------------------------------------------- |
| `MISSING_REQUIRED_FIELDS`              | 400  | `repositoryName` or `repositoryBranch` is missing.                                          |
| `INVALID_BRANCH_LENGTH`                | 400  | The branch name is longer than 256 characters.                                              |
| `BRANCH_NOT_FOUND`                     | 400  | The branch does not exist in the repository.                                                |
| `GIT_ALREADY_CONFIGURED`               | 400  | The application already has a GitHub App repository. Unlink it first.                       |
| `REPOSITORY_NOT_AVAILABLE`             | 403  | The Square Cloud GitHub App is not installed on the repository through your GitHub account. |
| `REPOSITORY_NOT_FOUND`                 | 404  | The repository does not exist or your GitHub account cannot see it.                         |
| `APP_NOT_FOUND`                        | 404  | The application does not exist or you are not its owner.                                    |
| `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | 409  | Another of your applications already links this repository and branch.                      |