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

# Deploy e integrazione Git

> Ispeziona la cronologia dei deploy, collega un repository tramite la GitHub App di Square Cloud oppure usa il flusso webhook legacy.

`app.deploys` espone il modulo [`DeploysModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/deploys.ts), che copre sia la cronologia dei deploy sia i due percorsi di integrazione con GitHub.

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

## Elencare la cronologia dei deploy

`app.deploys.list()` restituisce `Deployment[][]`, **un array interno per ogni deploy**, ognuno dei quali attraversa gli stati del ciclo di vita: `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);
    }
}
```

Appiattisci il risultato se vuoi un unico elenco cronologico:

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

<Warning>
  Nella v3 questo metodo restituiva un `Deployment[]` piatto. La v4 restituisce `Deployment[][]` in modo da poter raggruppare gli eventi per deploy. Usa `.flat()` per mantenere la forma precedente.
</Warning>

<Note>
  `Deployment.id` è ora un semplice SHA-1 del commit (40 caratteri esadecimali). Nella v3 era formattato come `` `git-${string}` ``.
</Note>

## Collegamento tramite la GitHub App di Square Cloud (consigliato)

`app.deploys.linkGithubApp({ repositoryName, repositoryBranch })` collega un repository GitHub all'applicazione tramite la GitHub App ufficiale.

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

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

Per rimuovere il collegamento:

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

<Warning>
  `linkGithubApp` e `unlinkGithubApp` richiedono un **token di sessione (JWT)** come chiave API: le semplici chiavi API non sono accettate da questi endpoint.
</Warning>

## Collegamento tramite il flusso webhook legacy

`app.deploys.integrateGithubWebhook(accessToken)` configura l'integrazione legacy basata su webhook usando un Personal Access Token di GitHub.

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

Passa `"@"` per rimuovere il webhook:

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

## Ispezionare la configurazione corrente

`app.deploys.current()` restituisce il collegamento alla GitHub App e l'URL del webhook attualmente configurati, se presenti.

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

È disponibile anche una scorciatoia `app.deploys.webhookURL()` che restituisce solo l'URL del webhook (o `undefined`).