Git Deploy 将仓库与站点连接起来，这样每次推送到您选择的分支时，都会克隆代码、运行构建并发布结果。本指南将介绍初始连接、完成设置所需的两个仓库端步骤、如何查看部署历史，以及决定 Node.js 应用如何构建的 buildpack 检测机制。
Git Deploy 的位置
打开网站，点击该站点，在站点左侧菜单中打开环境分组，然后选择 Git 部署。附近还有两个相关页面：
- 部署，该站点的完整部署历史，同样位于环境分组中。
- Buildpack，检测到的构建策略，仅适用于 Node.js 站点，位于应用分组中。
Git Deploy 页面对自身的说明很直白：连接一个仓库，之后每次推送到您配置的分支都会触发一次构建和部署。
连接仓库
- 选择您的提供商：GitHub、GitLab 或 Bitbucket。
- 输入仓库 URL。您需要使用 SSH 形式，例如
git@github.com:user/repo.git。 - 设置要部署的分支。该字段默认值为
main。 - 可选地设置构建命令，例如
npm run build。 - 可选地设置输出目录，例如
dist、public，或对于已经构建完成的仓库使用.。 - 点击连接仓库。
如果您的仓库本身已可直接部署（对于纯 PHP 或静态站点来说这是常见情况），请将构建命令和输出目录留空。
高级脚本
展开高级会显示两个额外字段：
- 部署前脚本，在构建之前运行。
- 部署后脚本，在部署之后运行。
对于那些必须在新代码就位后才能执行的操作，请使用部署后钩子：清除应用程序缓存、运行数据库迁移、重启某个工作进程。
推送时自动部署
卡片底部的开关控制推送是否会触发部署。开启时，每次推送到已配置的分支都会触发一次部署。关闭时，只有在您通过立即部署手动触发时才会运行部署。
在代码冻结期或发生故障期间，应关闭自动部署，而不是断开仓库连接。断开连接会丢弃部署密钥和 webhook 密钥，之后您必须重新完成这两个仓库端步骤。
在您的仓库中完成设置
在 KPanel 中连接仓库只是三个步骤中的第一步。在首次部署运行之前，页面会显示一个横幅，内容为完成设置：还需 2 个步骤，其中包含您所需的全部信息。
第 2 步：添加部署密钥
KapsuleHost 需要对您的仓库拥有读取权限才能克隆代码。该横幅会显示一个公钥，并附带复制密钥按钮。
将其粘贴到您仓库的部署密钥设置中。对于 GitHub，该横幅提供了添加到 GitHub 快捷方式，可直接跳转到正确的设置页面。只读权限即可，请勿授予写入权限。
第 3 步：添加 Webhook
Webhook 用于告知 KapsuleHost 发生了一次推送。该横幅会提供三个值：
| 字段 | 值 |
|---|---|
| 载荷 URL | 一个以 /api/git-deploy/webhook/ 结尾、并附加此站点 ID 的 URL |
| 密钥 | 一个自动生成的签名密钥，点击眼睛图标之前处于隐藏状态 |
| 内容类型 | application/json |
将每个值复制到您仓库的 webhook 设置中。对于 GitHub，有一个将 webhook 添加到 GitHub的快捷方式。请将内容类型设置为 JSON，而不是默认的表单编码格式，否则载荷将无法解析。
请像对待密码一样对待 webhook 密钥。任何获得该密钥以及载荷 URL 的人，都可以触发您站点的一次部署。这两个值仅会展示给已经拥有该站点管理权限的人，并且该密钥在您点击眼睛图标之前始终处于隐藏状态。
手动部署
在 Git Deploy 页面点击立即部署，即可在不推送提交的情况下构建并部署已配置分支的当前最新代码。无论自动部署是否开启，此功能都可以使用，这正是它在冻结期内成为合适工具的原因：推送会被忽略，但您仍然可以发布修复。
查看部署历史
打开环境，然后选择部署。该页面标题为部署历史，按时间从新到旧列出由 webhook 或手动触发的每一次部署。
每一行包含：
- 一个状态图标和简短的提交 SHA，分支以标签形式显示。
- 提交信息，如果没有可显示的提交信息，则显示手动部署。
- 作者、距今的时间、耗时，以及触发方式。
- 一个状态标签。
状态包括待处理、构建中、部署中、成功和失败。只要有任务正在进行中，页面就会每五秒自动刷新一次，并在表格下方显示自动刷新中的提示，因此您可以让页面保持打开状态，实时查看部署完成情况。
部署失败时
失败的行右侧会出现一个错误按钮。点击它即可在页面内联展开捕获到的错误输出，而无需离开当前页面。该输出就是构建过程本身产生的错误文本，因此通常会指明出错的文件或命令。
请按以下顺序排查：阅读错误信息，在本地复现相同的构建命令，修复问题，然后推送。如果构建在本地可以成功但在此处失败，差异几乎总是环境方面的问题，例如您机器上全局安装但未声明的依赖，或者某个文件存在于工作目录中但未提交。
Buildpack 检测
在 Node.js 站点上，应用分组中的 Buildpack 页面会显示 KapsuleHost 决定如何构建您应用的方式。检测过程会扫描仓库根目录下的文件，并以第一个匹配项为准：
| 检测结果 | 触发条件 |
|---|---|
| 自定义 buildpack | 根目录下存在 kapsule.config.yaml 或 kapsule.config.yml |
| Dockerfile buildpack | 根目录下存在 Dockerfile |
| Node.js | package.json 中存在 start、build 或 dev 脚本 |
| Python | requirements.txt 或 pyproject.toml |
| PHP | composer.json |
| 静态 | 根目录下存在 index.html |
如果没有任何匹配项，页面会予以说明，并列出支持的触发条件。添加 Dockerfile 或 kapsule.config.yaml 即可显式接管构建过程。
运行构建
点击运行构建即可将其加入队列。构建进行期间，页面每三秒轮询一次，最近的构建表格会显示最近几次运行的开始时间、类型、状态、耗时以及生成的镜像引用。点击某一行可查看其日志尾部内容。
同一时间只能有一个构建在进行。如果在已有构建排队或运行时再次触发，系统会拒绝并提示构建已在进行中，这是刻意设计的：两个构建同时写入相同的输出，正是导致站点部署到一半的原因。
断开连接
点击断开连接并确认。确认提示会明确说明影响范围：Git 部署配置和部署密钥将被移除，您的站点文件不会受到影响。站点将继续提供上一次部署的内容。
之后请在您的仓库设置中删除部署密钥和 webhook，完成清理工作。即使不删除，它们也只会失效，但遗留的失效条目会让下一次审查更加困难。
故障排除
推送没有触发任何操作。 首先检查自动部署开关，然后检查您仓库中的 webhook 设置。大多数服务商会显示最近的投递记录及其响应代码，可以立即判断请求是否已从您的仓库发出。
克隆失败。 可能是部署密钥缺失、粘贴时带入了换行符，或添加到了错误的仓库。请使用复制密钥按钮重新复制，而不要手动选中文本。
部署成功但站点没有变化。 很可能是输出目录设置有误。如果您的构建将文件写入 dist 而输出目录却为空，那么构建出的文件将永远无法到达对外提供服务的根目录。
所有内容都显示待处理且一直没有变化。 该部署已被加入队列但从未被执行。请手动触发立即部署，并在部署页面查看是否有错误行。
接下来可以了解
- 为 Pull Request 预览部署 在此设置基础上为每个 PR 添加一个专属 URL。
- 为站点存储应用密钥，了解您的构建和运行时所需的凭据。
- 站点活动日志 记录在此处所做的配置更改。