> ## 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 com POST /v2/apps/{app_id}/deploy/github-app, para cada push nessa branch fazer deploy.

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

Requer uma chave de API com o [escopo](/pt-br/api-reference/authentication#escopos) `apps:deploy`.

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 faça o deploy da 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 deploy 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`. Essa conta do GitHub também precisa de permissão de escrita (push) ou admin no repositório: só leitura falha com `REPOSITORY_PERMISSION_REQUIRED`. 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. Um repositório e branch só pode estar vinculado a uma aplicação em toda a plataforma, seja de quem for. Vincular invalida a resposta em cache de [Obter o deploy 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 da sua aplicação no dashboard.
</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 fazem o deploy da aplicação. Até 256 caracteres, e ela precisa existir no repositório com exatamente esse nome.
</ParamField>

## Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida: `success` se foi, `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 faz o deploy da 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_PERMISSION_REQUIRED` | 403 | Sua conta do GitHub conectada só tem acesso de leitura ao repositório. Ela precisa de permissão de escrita (push) ou admin. |
| `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, de qualquer conta, já vincula este repositório e branch. A mensagem só cita essa aplicação quando ela é sua. |
| `FAILED_TO_FETCH` | 502 | O GitHub não confirmou o branch. Tente novamente. |

## Relacionados

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


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