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

# デプロイと Git 連携

> デプロイ履歴を確認したり、Square Cloud GitHub App でリポジトリを連携したり、レガシーな webhook フローを使用したりできます。

`app.deploys` は [`DeploysModule`](https://github.com/squarecloudofc/sdk-api-js/blob/main/src/modules/deploys.ts) を公開しており、デプロイのタイムラインと 2 つの GitHub 連携パスの両方をカバーします。

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

## デプロイ履歴の一覧取得

`app.deploys.list()` は `Deployment[][]` を返します。**デプロイごとに 1 つの内側配列**があり、それぞれがライフサイクルの各状態 `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);
    }
}
```

単一の時系列リストが欲しい場合は結果をフラット化します。

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

<Warning>
  v3 ではこのメソッドはフラットな `Deployment[]` を返していました。v4 では `Deployment[][]` を返すため、イベントをデプロイ単位でグループ化できます。以前の形式を維持するには `.flat()` を使用してください。
</Warning>

<Note>
  `Deployment.id` は現在、単なるコミットの SHA-1（40 桁の 16 進数）になりました。v3 では `` `git-${string}` `` の形式でフォーマットされていました。
</Note>

## Square Cloud GitHub App での連携（推奨）

`app.deploys.linkGithubApp({ repositoryName, repositoryBranch })` は、公式の GitHub App を介して GitHub リポジトリをアプリケーションに連携します。

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

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

連携を解除するには次のようにします。

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

<Warning>
  `linkGithubApp` と `unlinkGithubApp` は API キーとして **セッショントークン（JWT）** が必要です。これらの endpoint はプレーンな API キーを受け付けません。
</Warning>

## レガシー webhook フローでの連携

`app.deploys.integrateGithubWebhook(accessToken)` は、GitHub の Personal Access Token を使用してレガシーな webhook ベースの連携を設定します。

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

webhook を削除するには `"@"` を渡します。

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

## 現在の設定の確認

`app.deploys.current()` は、現在設定されている GitHub App の連携情報と webhook URL があればそれを返します。

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

webhook URL のみ（または `undefined`）を返すショートカット `app.deploys.webhookURL()` もあります。