Skip to content

Hook 接口 ​

Webhook 让代码托管平台在 push / tag 时自动触发部署。项目与任务共用一套令牌(hk_ 前缀)与触发入口,管理路由分两组、触发路由只有一个。GitLab 端到端配置见 GitLab Hook。

管理路由 ​

方法与路径权限说明
GET /projects/{key}/hooks可见列出项目的 Hook 令牌
POST /projects/{key}/hooksowner/admin创建
GET /tasks/{key}/hooks可见列出任务的 Hook 令牌
POST /tasks/{key}/hooksowner/admin创建
DELETE /hooks/{id}owner/admin删除(按令牌 ID,项目/任务通用)
POST /hook-tokens/{id}/resetowner/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/json
http
POST /api/v1/hooks
X-Deploy-Token: hk_xxxxxxxx
Content-Type: application/json

Header 方式适合 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)。

场景errorCodeHTTP
缺令牌 / 令牌无效 / 已过期40100401
令牌被禁用(enabled=false)40300200
目标 hookEnabled=false 或已归档40300200
超过频率限制42900200
任务传 withDependencies=true、依赖校验失败等40000200
目标项目/任务已删除40400200

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 参考。