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

# Deploys e integração Git

> Inspecione o histórico de deploys, vincule um repositório através do GitHub App da Square Cloud ou use o fluxo legado de webhook.

`app.deploys` expõe o [`DeploysModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/deploys.ts), que cobre tanto a linha do tempo dos deploys quanto os dois caminhos de integração com o GitHub.

```typescript theme={null}
const app = await api.applications.fetch("abc123def456abc123def456");
app.deploys; // DeploysModule
```

## Listando o histórico de deploys

`app.deploys.list()` retorna `Deployment[][]` — **um array interno por deploy**, cada um percorrendo os estados: `pending → clone → commit → restarting → success | error`.

```typescript theme={null}
const history = await app.deploys.list();

for (const timeline of history) {
    const last = timeline.at(-1);
    console.log(`Deploy ${last?.id} terminou como ${last?.state}`);

    for (const event of timeline) {
        if (event.state === "clone")  console.log(`  branch clonada: ${event.branch}`);
        if (event.state === "commit") console.log(`  arquivos`, event.files);
    }
}
```

Use `.flat()` se quiser uma única lista cronológica:

```typescript theme={null}
const flat = history.flat();
```

<Warning>
  Na v3 esse método retornava um `Deployment[]` plano. A v4 retorna `Deployment[][]` para agrupar eventos por deploy. Use `.flat()` para manter o formato antigo.
</Warning>

<Note>
  `Deployment.id` agora é um SHA-1 de commit (40 chars hex). Na v3 era formatado como `` `git-${string}` ``.
</Note>

## Vinculando via GitHub App da Square Cloud (recomendado)

`app.deploys.linkGithubApp({ repositoryName, repositoryBranch })` vincula um repositório GitHub à aplicação por meio do GitHub App oficial.

```typescript theme={null}
const repo = await app.deploys.linkGithubApp({
    repositoryName: "octocat/hello-world",
    repositoryBranch: "main",
});

console.log(`Vinculado ${repo.full_name}#${repo.branch}`);
```

Para remover o vínculo:

```typescript theme={null}
await app.deploys.unlinkGithubApp();
```

<Warning>
  `linkGithubApp` e `unlinkGithubApp` exigem um **session token (JWT)** como chave de API — chaves de API comuns não são aceitas nesses endpoints.
</Warning>

## Vinculando via webhook (legado)

`app.deploys.integrateGithubWebhook(accessToken)` configura a integração legada por webhook usando um Personal Access Token do GitHub.

```typescript theme={null}
const webhookUrl = await app.deploys.integrateGithubWebhook("ghp_xxx...");
console.log(`Configure o GitHub para enviar POST para: ${webhookUrl}`);
```

Passe `"@"` para remover o webhook:

```typescript theme={null}
await app.deploys.integrateGithubWebhook("@");
```

## Inspecionando a configuração atual

`app.deploys.current()` retorna o vínculo do GitHub App e a URL do webhook configurada, se houver.

```typescript theme={null}
const current = await app.deploys.current();

console.log(current.app);     // vínculo do GitHub App (ou null)
console.log(current.webhook); // URL do webhook legado (ou null)
```

Há também o atalho `app.deploys.webhookURL()`, que retorna apenas a URL do webhook (ou `undefined`).