> ## 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)，它同时涵盖部署时间线和两种 GitHub 集成路径。

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

## 列出部署历史

`app.deploys.list()` 返回 `Deployment[][]` —— **每个内层数组对应一次部署**，各自贯穿生命周期状态：`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 位十六进制字符）。在 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` 要求使用 **会话令牌（JWT）** 作为你的 API 密钥 —— 这些 endpoint 不接受普通的 API 密钥。
</Warning>

## 通过旧版 webhook 流程关联

`app.deploys.integrateGithubWebhook(accessToken)` 使用 GitHub 个人访问令牌配置旧版基于 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)
```

还有一个快捷方法 `app.deploys.webhookURL()`，它只返回 webhook URL（或 `undefined`）。