主题
Hook 接口
Webhook 让代码托管平台在 push / tag 时自动触发部署。项目与任务共用一套令牌(hk_ 前缀)与触发入口,管理路由分两组、触发路由只有一个。GitLab 端到端配置见 GitLab Hook。
管理路由
| 方法与路径 | 权限 | 说明 |
|---|---|---|
GET /projects/{key}/hooks | 可见 | 列出项目的 Hook 令牌 |
POST /projects/{key}/hooks | owner/admin | 创建 |
GET /tasks/{key}/hooks | 可见 | 列出任务的 Hook 令牌 |
POST /tasks/{key}/hooks | owner/admin | 创建 |
DELETE /hooks/{id} | owner/admin | 删除(按令牌 ID,项目/任务通用) |
POST /hook-tokens/{id}/reset | owner/admin | 重置(旧令牌立即失效,返回新明文) |
没有「禁用」或「修改过期时间」接口:enabled 创建后固定为 true,expiresInDays 只在创建时生效。要停用只能删除或重置;临时整体关闭用项目/任务的 hookEnabled=false 开关(见 项目与任务接口)。
列表 data 为 HookToken 数组,任何接口都不返回令牌明文/哈希:
| 字段 | 说明 |
|---|---|
id | 令牌 ID |
projectId / taskId / targetKind | 所属项目 / 任务(project/task) |
name / prefix | 名称 / 前 8 字符(如 hk_xxxxx),仅用于识别 |
enabled / expiresAt | 是否启用 / 过期时间(null 为永不过期) |
lastUsedAt / lastUsedIp / callCount | 最近调用时间 / 来源 IP / 累计调用次数 |
createdAt | 创建时间 |
创建与重置
POST /projects/{key}/hooks(任务同理),body:
json
{ "name": "gitlab-push", "expiresInDays": 90 }name 缺省 default;expiresInDays 缺省或 ≤0 表示永不过期。项目/任务不存在或不可见 → 40400。响应 data(token 明文只出现这一次,请立即保存):
json
{
"id": 7, "projectId": 3, "taskId": null, "targetKind": "project",
"name": "gitlab-push", "prefix": "hk_xxxxx", "enabled": true,
"expiresAt": "2026-05-01T00:00:00Z", "createdAt": "2026-02-01T00:00:00Z",
"token": "hk_xxxxxxxx",
"hookPath": "/api/v1/hooks/hk_xxxxxxxx"
}POST /hook-tokens/{id}/reset:无 body,响应 data:
json
{ "id": 7, "token": "hk_xxxxxxxx", "hookPath": "/api/v1/hooks/hk_xxxxxxxx" }令牌为 hk_ + 32 位随机字符(无易混字符字母表),服务端只存 SHA-256 哈希;每次调用异步累加 callCount/lastUsedAt/lastUsedIp 并写审计。项目/任务被删除时其 Hook 令牌级联删除。
触发入口
两种方式等价,路径令牌优先于请求头:
http
POST /api/v1/hooks/hk_xxxxxxxx
Content-Type: application/jsonhttp
POST /api/v1/hooks
X-Deploy-Token: hk_xxxxxxxx
Content-Type: application/jsonHeader 方式适合 GitLab/Gitea 这类「URL + Secret Token 分离」的配置,且避免令牌进访问日志;路径方式适合 GitHub 这类只能填 URL 的平台。触发接口无需登录态。
触发 body
body 可完全省略(全部用默认值):
json
{
"branch": "main",
"env": { "TAG": "v1.2.3" },
"commandIds": [10, 11],
"withDependencies": true,
"async": true,
"idempotencyKey": "push-abc123"
}| 字段 | 说明 |
|---|---|
branch | 项目:覆盖 Git 分支/Tag;任务:无 Git 准备阶段,忽略 |
env | 触发参数覆盖,受 allowEnvOverride 约束 |
commandIds | 项目:命令行 ID;任务:步骤位置序号(1 起) |
withDependencies | 仅项目可用;任务传 true → 40000 |
async | 默认 true(202 立即返回);显式 false 转同步等待 |
idempotencyKey | 已解析但未使用:服务端不做幂等去重,重试会真的再跑一次(源码与契约的差异) |
与登录态 /run 的另一个差异:Hook 触发不校验 commandIds 与 withDependencies 互斥,两者同传时命令过滤只作用于主项目、依赖仍全量构建。建议不要这样组合。
平台侧对接:GitLab 用 X-Gitlab-Event: Push Hook 的 payload(服务端解析 ref/checkout_sha 等);也可显式传上述 body 覆盖。分支过滤、tag 处理等策略见 Hook 自动部署。
异步与同步响应
默认异步,HTTP 202,data:
json
{
"runId": 88, "projectKey": "my-app",
"targetKey": "my-app", "targetKind": "project",
"buildNumber": 13, "status": "queued", "async": true,
"pipelineId": "", "statusUrl": "/api/v1/runs/88",
"logUrl": "/api/v1/runs/88/log"
}任务目标时 projectKey 换成 taskKey。带依赖时另有 dependencies[] 与 dependencyCount。targetKey/targetKind/pipelineId/dependencyCount 为源码扩展字段,契约未列。
同步等待:query ?wait=true(或 wait=1)或 body async:false,服务端阻塞至终态,上限 30 分钟。终态返回 HTTP 200,data 在异步字段基础上追加:
json
{ "async": false, "exitCode": 0, "durationMs": 8123, "errorMsg": "" }超过 30 分钟仍未结束也返回 200,但 status 可能仍是 running——调用方必须检查 status 而非只看 HTTP 码,未终态时改用 statusUrl 轮询或 WS 跟随。
限流与错误
限流按令牌计,固定 1 分钟窗口,默认 60 次/分钟;系统设置 hookRateLimitPerMinute 可改(0 表示不限),见 系统与中间件接口。超限返回 42900(showType=1,HTTP 200)。
| 场景 | errorCode | HTTP |
|---|---|---|
| 缺令牌 / 令牌无效 / 已过期 | 40100 | 401 |
令牌被禁用(enabled=false) | 40300 | 200 |
目标 hookEnabled=false 或已归档 | 40300 | 200 |
| 超过频率限制 | 42900 | 200 |
任务传 withDependencies=true、依赖校验失败等 | 40000 | 200 |
| 目标项目/任务已删除 | 40400 | 200 |
curl 示例
异步触发(拿到 runId 后轮询状态):
bash
curl -s -X POST https://deploy.example.com/api/v1/hooks/hk_xxxxxxxx \
-H 'Content-Type: application/json' \
-d '{"branch":"main","withDependencies":true}'同步等待结果(CI 脚本里用退出码判断成败):
bash
resp=$(curl -s -X POST 'https://deploy.example.com/api/v1/hooks?wait=true' \
-H 'X-Deploy-Token: hk_xxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{"branch":"release-1.2"}')
echo "$resp"
# 解析 .data.status,必须等于 success 才算部署成功CLI 对应命令 deploy project hooks / deploy task hooks,见 CLI 参考。