> ## 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 integración con Git

> Inspecciona el historial de deploys, vincula un repositorio mediante la GitHub App de Square Cloud o usa el flujo heredado por webhook.

`app.deploys` expone el [`DeploysModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/deploys.ts), que abarca tanto la línea de tiempo de deploys como las dos vías de integración con GitHub.

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

## Listado del historial de deploys

`app.deploys.list()` devuelve `Deployment[][]`: **un array interno por cada deploy**, cada uno recorriendo los estados del ciclo de vida: `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} ended as ${last?.state}`);

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

Aplana el resultado si quieres una única lista cronológica:

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

<Warning>
  En la v3 este método devolvía un `Deployment[]` plano. La v4 devuelve `Deployment[][]` para que puedas agrupar los eventos por deploy. Usa `.flat()` para conservar la forma anterior.
</Warning>

<Note>
  `Deployment.id` ahora es un SHA-1 de commit plano (40 caracteres hexadecimales). En la v3 estaba formateado como `` `git-${string}` ``.
</Note>

## Vinculación mediante la GitHub App de Square Cloud (recomendado)

`app.deploys.linkGithubApp({ repositoryName, repositoryBranch })` vincula un repositorio de GitHub a la aplicación a través de la GitHub App oficial.

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

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

Para eliminar la vinculación:

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

<Warning>
  `linkGithubApp` y `unlinkGithubApp` requieren un **token de sesión (JWT)** como clave de API: estos endpoints no aceptan claves de API normales.
</Warning>

## Vinculación mediante el flujo heredado por webhook

`app.deploys.integrateGithubWebhook(accessToken)` configura la integración heredada basada en webhook usando un Personal Access Token de GitHub.

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

Pasa `"@"` para eliminar el webhook:

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

## Inspección de la configuración actual

`app.deploys.current()` devuelve la vinculación de la GitHub App y la URL del webhook configuradas actualmente, si las hay.

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

console.log(current.app);     // GitHub App linkage (or null)
console.log(current.webhook); // legacy webhook URL (or null)
```

También existe un atajo `app.deploys.webhookURL()` que devuelve solo la URL del webhook (o `undefined`).