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

# Vincular repositório do GitHub App

> Vincule um repositório e uma branch do GitHub a uma aplicação pelo GitHub App da Square Cloud.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Este endpoint vincula uma aplicação a um repositório e a uma branch do GitHub pelo GitHub App da Square Cloud, para que cada push nessa branch implante a aplicação. É a alternativa recomendada ao [Configurar webhook do GitHub](/pt-br/api-reference/endpoint/apps/deploy/webhooks): nenhum token de acesso pessoal fica guardado, e cada implantação aparece como um Check Run no commit.

Antes de chamar, conecte sua conta do GitHub à Square Cloud e instale o GitHub App da Square Cloud no repositório. O repositório precisa estar coberto por uma instalação da sua própria conta do GitHub; caso contrário, a requisição falha com `REPOSITORY_NOT_AVAILABLE`. Funciona com uma chave de API que tenha o escopo `apps:deploy`, e só o proprietário da aplicação pode chamá-lo.

Uma aplicação tem um vínculo do GitHub App por vez, então [desvincule](/pt-br/api-reference/endpoint/apps/deploy/github-app-unlink) o repositório atual antes de vincular outro, e o mesmo repositório e branch não podem estar vinculados a duas aplicações suas. Vincular invalida a resposta em cache de [Obter implantação atual](/pt-br/api-reference/endpoint/apps/deploy/info). As chamadas são limitadas a 3 por 60 segundos por usuário, compartilhadas com o desvínculo.

### Parâmetros

<ParamField path="app_id" type="string" placeholder="ID da Aplicação" required>
  O ID da aplicação. Você pode encontrá-lo na URL do painel da sua aplicação.
</ParamField>

<ParamField body="repositoryName" type="string" placeholder="octocat/hello-world" required>
  O nome completo do repositório, no formato `dono/repositório`.
</ParamField>

<ParamField body="repositoryBranch" type="string" placeholder="main" required>
  A branch cujos pushes implantam a aplicação. Até 256 caracteres, e ela precisa existir no repositório.
</ParamField>

### Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida. `success` se bem-sucedida, `error` se não.
</ResponseField>

<ResponseField name="response" type="object">
  O conteúdo da resposta.

  <Expandable title="Alternar objeto">
    <ResponseField name="repository" type="object">
      O repositório vinculado.

      <Expandable title="Alternar objeto">
        <ResponseField name="id" type="number">
          O ID do repositório no GitHub.
        </ResponseField>

        <ResponseField name="full_name" type="string">
          O nome completo do repositório.
        </ResponseField>

        <ResponseField name="branch" type="string">
          A branch que implanta a aplicação.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

### Erros comuns

| Código                                 | HTTP | Significado                                                                              |
| -------------------------------------- | ---- | ---------------------------------------------------------------------------------------- |
| `MISSING_REQUIRED_FIELDS`              | 400  | Falta `repositoryName` ou `repositoryBranch`.                                            |
| `INVALID_BRANCH_LENGTH`                | 400  | O nome da branch tem mais de 256 caracteres.                                             |
| `BRANCH_NOT_FOUND`                     | 400  | A branch não existe no repositório.                                                      |
| `GIT_ALREADY_CONFIGURED`               | 400  | A aplicação já tem um repositório do GitHub App. Desvincule-o primeiro.                  |
| `REPOSITORY_NOT_AVAILABLE`             | 403  | O GitHub App da Square Cloud não está instalado no repositório pela sua conta do GitHub. |
| `REPOSITORY_NOT_FOUND`                 | 404  | O repositório não existe ou sua conta do GitHub não tem acesso a ele.                    |
| `APP_NOT_FOUND`                        | 404  | A aplicação não existe ou você não é o proprietário.                                     |
| `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | 409  | Outra aplicação sua já vincula este repositório e branch.                                |