> ## 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 & Git-Integration

> Deploy-Verlauf einsehen, ein Repository über die Square Cloud GitHub App verknüpfen oder den klassischen Webhook-Ablauf nutzen.

`app.deploys` stellt das [`DeploysModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/deploys.ts) bereit, das sowohl die Deploy-Timeline als auch die beiden GitHub-Integrationswege abdeckt.

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

## Den Deploy-Verlauf auflisten

`app.deploys.list()` gibt `Deployment[][]` zurück — **ein inneres Array pro Deploy**, das jeweils die Lebenszyklus-Zustände durchläuft: `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);
    }
}
```

Reduziere das Ergebnis, wenn du eine einzige chronologische Liste möchtest:

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

<Warning>
  In v3 gab diese Methode ein flaches `Deployment[]` zurück. v4 gibt `Deployment[][]` zurück, damit du Ereignisse nach Deploy gruppieren kannst. Verwende `.flat()`, um die alte Form beizubehalten.
</Warning>

<Note>
  `Deployment.id` ist nun ein einfacher Commit-SHA-1 (40 Hex-Zeichen). In v3 war er als `` `git-${string}` `` formatiert.
</Note>

## Verknüpfen über die Square Cloud GitHub App (empfohlen)

`app.deploys.linkGithubApp({ repositoryName, repositoryBranch })` verknüpft ein GitHub-Repository über die offizielle GitHub App mit der Anwendung.

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

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

Um die Verknüpfung zu entfernen:

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

<Warning>
  `linkGithubApp` und `unlinkGithubApp` erfordern ein **Session-Token (JWT)** als API-Schlüssel — einfache API-Schlüssel werden von diesen Endpoints nicht akzeptiert.
</Warning>

## Verknüpfen über den klassischen Webhook-Ablauf

`app.deploys.integrateGithubWebhook(accessToken)` konfiguriert die klassische Webhook-basierte Integration mit einem GitHub Personal Access Token.

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

Übergib `"@"`, um den Webhook zu entfernen:

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

## Die aktuelle Konfiguration einsehen

`app.deploys.current()` gibt die aktuell konfigurierte GitHub-App-Verknüpfung und Webhook-URL zurück, sofern vorhanden.

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

Es gibt außerdem eine Abkürzung `app.deploys.webhookURL()`, die nur die Webhook-URL zurückgibt (oder `undefined`).