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

# SDK JavaScript: deploys pelo GitHub

> Faça deploy a partir do GitHub com api.apps.deploys: configure um webhook, vincule um repositório pelo GitHub App da Square Cloud e leia o histórico de deploys.

`api.apps.deploys` conecta uma aplicação ao GitHub para que um push faça o deploy dela. Há duas formas de fazer isso: um **webhook** que você adiciona ao repositório, ou o **GitHub App da Square Cloud**.

Os exemplos usam o cliente `api` de [Criando o cliente](/pt-br/sdks/js/client#criando-o-cliente). `appId` é o id de uma das suas aplicações: [`api.account.me()`](/pt-br/sdks/js/client#conta) lista todas.

## Webhook

`deploys.setWebhook(appId, accessToken)` configura deploys via webhook do GitHub com um token de acesso do GitHub (`ghp_...` ou `github_pat_...`) e retorna a URL do webhook a ser adicionada ao seu repositório.

```typescript theme={"system"}
const url = await api.apps.deploys.setWebhook(appId, process.env.GITHUB_TOKEN!);

console.log(url); // add it as a webhook in the repository settings
```

Passe `"@"` como token para remover o webhook. O método então retorna `""`.

```typescript theme={"system"}
await api.apps.deploys.setWebhook(appId, "@");
```

Um token inválido resulta em 400 `INVALID_ACCESS_TOKEN`.

## GitHub App

`deploys.linkGithubApp(appId, repository, branch)` vincula um repositório instalado pelo GitHub App da Square Cloud. Requer o escopo `apps:deploy`.

```typescript theme={"system"}
const repo = await api.apps.deploys.linkGithubApp(appId, "octocat/hello-world", "main");

console.log(repo.id, repo.full_name, repo.branch);
```

`deploys.unlinkGithubApp(appId)` remove o vínculo. Para vincular outro repositório ou branch, desvincule primeiro.

```typescript theme={"system"}
await api.apps.deploys.unlinkGithubApp(appId);
```

Vincular e desvincular compartilham um limite de **3 chamadas a cada 60 segundos**.

| Status | Código | Quando |
| - | - | - |
| 400 | `GIT_ALREADY_CONFIGURED` | A aplicação já tem um repositório vinculado: desvincule-o primeiro |
| 400 | `GIT_NOT_CONFIGURED` | `unlinkGithubApp` sem nada vinculado |
| 400 | `BRANCH_NOT_FOUND`, `INVALID_BRANCH_LENGTH` | A branch não existe, ou seu nome tem mais de 256 caracteres |
| 403 | `GITHUB_NOT_CONNECTED` | Sua conta não tem uma instalação do GitHub App |
| 403 | `REPOSITORY_NOT_AVAILABLE` | O GitHub App não está instalado no repositório por meio da sua conta do GitHub |
| 403 | `REPOSITORY_PERMISSION_REQUIRED` | Sua conta do GitHub não tem acesso de escrita ao repositório |
| 404 | `REPOSITORY_NOT_FOUND` | O repositório não existe ou não está visível |
| 409 | `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | Outra aplicação, de qualquer conta, já vincula este repositório e branch. O id dela aparece em `message` apenas quando essa aplicação é sua |
| 502 | `FAILED_TO_FETCH` | O GitHub não confirmou a branch: é seguro tentar novamente |

## Configuração atual

`deploys.current(appId)` retorna o que está configurado: `app` para o vínculo do GitHub App, `webhook` para a URL do webhook. Retorna `{}` quando nada está configurado.

```typescript theme={"system"}
const { app, webhook } = await api.apps.deploys.current(appId);

if (app) console.log(app.name, app.branch); // e.g. "octocat/hello-world" "main"
if (webhook) console.log(webhook);
```

## Histórico de deploys

`deploys.list(appId)` retorna uma **linha do tempo por deploy**, cada uma um array de eventos, do evento mais antigo para o mais recente. Apenas deploys via Git (pushes por webhook e GitHub App) são registrados.

```typescript theme={"system"}
for (const timeline of await api.apps.deploys.list(appId)) {
    const last = timeline.at(-1);
    console.log(last?.id, last?.state, last?.date);

    if (last?.state === "error") console.log(last.code, last.message);
}
```

| Campo | Descrição |
| - | - |
| `id` | O SHA do commit |
| `state` | `pending`, `clone`, `commit`, `restarting`, `success` ou `error` |
| `date` | Quando o evento aconteceu |
| `source` | Sempre `"git"` |
| `branch` | Em eventos `clone` |
| `files` | Em eventos `commit`: `{ added, removed, modified }` |
| `code` / `message` | Em eventos `error`: por que o deploy falhou (por exemplo, `CLONE_FAILED`) |

## Próximos passos

<CardGroup cols={3}>
  <Card title="Rede" icon="globe" href="/pt-br/sdks/js/network">
    Analytics, DNS, domínios personalizados e cache.
  </Card>

  <Card title="Referência da API de deploy" icon="code" href="/pt-br/api-reference/endpoint/apps/deploy/list">
    Os endpoints REST por trás destes métodos.
  </Card>

  <Card title="Deploys do GitHub pela CLI" icon="terminal" href="/pt-br/cli-reference/github-deploys">
    As mesmas ações pelo terminal.
  </Card>
</CardGroup>


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