通过部署钩子触发部署

部署钩子是一个秘密 URL，当有东西向它发送 HTTP POST 请求时，会将新部署加入队列。没有身份验证标头：URL 的保密性就是身份验证。使用钩子让无头 CMS、cron 作业、CI 管道或任何其他 webhook 无需 git push 就能重新构建您的项目。

在哪里找到部署钩子

钩子有自己的选项卡：在 Orbit 中打开您的项目，然后点击 Hooks，位于 /orbit/<project-id>/hooks。

同一个 Deploy hooks 面板也出现在项目的 Settings 选项卡的中间位置，因此您可以从任一位置对其进行管理。

创建部署钩子

1. 打开 Orbit，然后打开您的项目，然后打开 Hooks。
2. 点击 Add deploy hook。
3. 输入一个 Hook name，该名称在六个月后仍然有意义。占位符建议的格式：例如"Contentful publish"、"Nightly cron"。
4. 选择一个 Target environment。它默认为 Production (default)。如果您的项目有一个分阶段环境，您可以改为将钩子指向分阶段环境。
5. 点击 Create hook。

钩子出现在列表中，并显示其 URL、一个 Copy URL 按钮和一个 Delete hook 按钮。

钩子 URL

钩子 URL 看起来像这样：

https://kpanel.kapsulehost.com/api/orbit/hooks/<token>

该令牌是创建钩子时生成的唯一秘密。

触发钩子

发送 POST 请求。不需要请求体和标头。

curl -X POST \
  https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

Orbit 响应 HTTP 202 和部署 ID。部署将在几秒内出现在 Deployments 选项卡上。

钩子实际部署的内容

钩子解析其目标环境（您选择的环境或项目的生产环境），读取该环境的分支，并向您的 git 提供商请求该分支的当前头提交。然后它将该提交的部署加入队列。

这有三个值得了解的后果：

• 钩子总是部署分支头。 您不能在请求体中传递提交 SHA 或分支名称；请求体被完全忽略。
• 钩子需要有效的提供商连接。 如果您已断开 GitHub、GitLab 或 Bitbucket 的连接，钩子将无法读取分支头，并会出现错误而不是部署过时代码。
• 钩子重新运行完整构建。 这不是回滚，也不是升级；它是对分支上当前内容的新鲜构建。

重复和重叠调用

Orbit 以明智的方式处理钩子调用的突发流量，而不是为每一个调用都加入一个构建。

• 如果对该环境的同一提交的部署已在进行中，钩子将返回现有部署并将响应标记为已去重。不会启动第二个构建。
• 如果一个针对该环境上不同提交的构建正在运行，它将被自动取消并替换为新的构建，因此您不需要为一个输出已被超越的构建付费。

连接无头 CMS

大多数无头 CMS 都有"发布时的 webhook"功能。模式总是一样的：将 webhook 指向您的钩子 URL，使用 POST，并将身份验证设置留空。

Contentful

1. 转到 Settings，然后转到 Webhooks，然后点击 Add webhook。
2. 将 URL 设置为您的 Orbit 钩子 URL。
3. 将方法设置为 POST。
4. 将触发器设置为 Publish，或应该重建站点的任何内容事件。
5. 保存。

Sanity

在您的项目仪表板中，转到 API，然后转到 Webhooks，然后点击 Create webhook。将 URL 设置为您的钩子 URL，将方法设置为 POST，并选择数据集和触发事件。

Prismic

在仪表板中，转到 Settings，然后转到 Webhooks，并添加您的钩子 URL。Prismic 会在每个文档发布时调用它。

连接 Cron 作业或 CI 管道

任何可以发送 HTTP 请求的调度程序都可以：

# crontab: rebuild every night at 2am
0 2 * * * curl -fsS -X POST https://kpanel.kapsulehost.com/api/orbit/hooks/<your-token>

对于 CI，当您希望您的管道决定是否进行部署时，部署钩子是最简单的选项。这是 Bitbucket Pipelines 的推荐方法，因为 Orbit 的 CI 必需检查在 GitHub Actions 作业名称或 GitLab 管道上进行限制，而不是在 Bitbucket 上。

无需钩子按计划重新构建

如果您只想要定期重新构建，就根本不需要钩子。Settings 中的 Scheduled rebuild，在 Runtime 下，每小时、6 小时、12 小时、每天、每 2 天或每周自动重新构建生产环境。它是为 CMS 驱动站点的情况而专门构建的，没有需要保护的秘密 URL。

检查钩子活动

每个钩子行显示它被使用的次数和最后一次使用的时间，格式为"Used 14 times, last 3 Jul"。这是确认您的 CMS 在您认为的时候实际调用钩子的最快方法。

如果计数没有增加，问题在调用端：检查方法是否为 POST，URL 是否完全准确，以及集成是否没有在 TLS 或防火墙错误上默默失败。

删除钩子

点击该行上的 Delete hook 并确认。对话会警告使用它的任何服务都将停止工作，这正是发生的情况。

故障排除

当我调用钩子时什么都没发生。 检查方法是否为 POST。逐字检查 URL，包括令牌。检查 Hooks 选项卡上的钩子使用计数：如果它没有增加，请求从未到达。

钩子返回有关最新提交的错误。 Orbit 无法从您的 git 提供商读取分支头。从 Orbit 重新连接提供商，然后 New project，然后 Reconnect，并确认存储库仍然可访问。

钩子返回有关目标环境的错误。 钩子指向的环境不再存在，最可能是因为删除了分阶段环境。删除钩子并针对实时环境创建新的。

钩子触发但部署与上次相同。 这是去重行为：分支头没有改变，所以没有新的东西要构建。推送一个提交，或如果您特别想重新构建同一提交，请使用 Deploy now。

相关阅读

• 部署您的项目，了解部署限制及其中钩子绕过的部分
• 连接 Bitbucket 存储库，了解钩子解决的 CI 限制情况
• 环境变量，因为钩子触发的构建读取与任何其他构建相同的配置