> ## 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 with POST /v2/apps/{app_id}/deploy/github-app, so every push to that branch deploys it.

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

Requires an API key with the `apps:deploy` [scope](/en/api-reference/authentication#scopes).

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`. That GitHub account also needs write (push) or admin permission on the repository: read-only access fails with `REPOSITORY_PERMISSION_REQUIRED`. 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. A repository and branch can be linked to only one application on the whole platform, whoever owns it. 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 with this exact name.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Indicates whether the call was successful: `success` if it was, `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_PERMISSION_REQUIRED` | 403 | Your connected GitHub account has only read access to the repository. It needs write (push) or admin permission. |
| `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 application, from any account, already links this repository and branch. The message names that application only when it is yours. |
| `FAILED_TO_FETCH` | 502 | GitHub did not confirm the branch. Try again. |

## Related

* CLI: [`squarecloud app deploy github link`](/en/cli-reference/github-deploys#squarecloud-app-deploy-github-link)
* SDKs: [`api.apps.deploys.linkGithubApp()`](/en/sdks/js/deploys) (JavaScript), [`client.apps.deploys.link_github_app()`](/en/sdks/py/deploys) (Python), [`c.Apps.Deploys.LinkGithubApp()`](/en/sdks/go/deploys) (Go)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.