Help us learn about your current experience with the documentation. Take the survey.

系统钩子 API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

所有方法都需要管理员授权。

您可以从 GitLab 用户界面配置系统钩子的 URL 端点：

  1. 在左侧边栏底部，选择 管理员。
  2. 选择 系统钩子 (/admin/hooks)。

了解更多关于 系统钩子 的信息。

列出系统钩子

获取所有系统钩子的列表。

GET /hooks

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks"

示例响应：

[
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification":true,
    "url_variables": []
  }
]

获取系统钩子

根据 ID 获取系统钩子。

GET /hooks/:id
Attribute Type Required Description
id integer 是 钩子的 ID

示例请求：

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/1"

示例响应：

{
  "id": 1,
  "url": "https://gitlab.example.com/hook",
  "name": "Hook name",
  "description": "Hook description",
  "created_at": "2016-10-31T12:32:15.192Z",
  "push_events": true,
  "tag_push_events": false,
  "merge_requests_events": true,
  "repository_update_events": true,
  "enable_ssl_verification": true,
  "url_variables": []
}

添加新系统钩子

添加新的系统钩子。

POST /hooks
Attribute Type Required Description
url string 是 钩子 URL
name string 否 钩子名称（在 GitLab 17.1 中 引入）
description string 否 钩子描述（在 GitLab 17.1 中 引入）
token string 否 用于验证接收到的负载的密钥；此值不会在响应中返回
push_events boolean 否 为 true 时，钩子在推送事件时触发
tag_push_events boolean 否 为 true 时，钩子在推送新标签时触发
merge_requests_events boolean 否 在合并请求事件时触发钩子
repository_update_events boolean 否 在仓库更新事件时触发钩子
enable_ssl_verification boolean 否 触发钩子时进行 SSL 验证
push_events_branch_filter string 否 仅在匹配分支的推送事件时触发钩子
branch_filter_strategy string 否 按分支过滤推送事件。可能的值为 wildcard（默认）、regex 和 all_branches

示例请求：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks?url=https://gitlab.example.com/hook"

示例响应：

[
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification":true,
    "url_variables": []
  }
]

更新系统钩子

更新现有的系统钩子。

PUT /hooks/:hook_id
Attribute Type Required Description
hook_id integer 是 系统钩子的 ID
url string 否 钩子 URL
token string 否 用于验证接收到的负载的密钥；此值不会在响应中返回
push_events boolean 否 为 true 时，钩子在推送事件时触发
tag_push_events boolean 否 为 true 时，钩子在推送新标签时触发
merge_requests_events boolean 否 在合并请求事件时触发钩子
repository_update_events boolean 否 在仓库更新事件时触发钩子
enable_ssl_verification boolean 否 触发钩子时进行 SSL 验证
push_events_branch_filter string 否 仅在匹配分支的推送事件时触发钩子
branch_filter_strategy string 否 按分支过滤推送事件。可能的值为 wildcard（默认）、regex 和 all_branches

测试系统钩子

使用模拟数据执行系统钩子。

POST /hooks/:id
Attribute Type Required Description
id integer 是 钩子的 ID

示例请求：

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/1"

响应始终是模拟数据：

{
   "project_id" : 1,
   "owner_email" : "[email protected]",
   "owner_name" : "Someone",
   "name" : "Ruby",
   "path" : "ruby",
   "event_name" : "project_create"
}

删除系统钩子

删除系统钩子。

DELETE /hooks/:id
Attribute Type Required Description
id integer 是 钩子的 ID

示例请求：

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks/2"

设置 URL 变量

PUT /hooks/:hook_id/url_variables/:key

支持的属性：

Attribute Type Required Description
hook_id integer 是 系统钩子的 ID。
key string 是 URL 变量的键。
value string 是 URL 变量的值。

成功时，此端点返回响应代码 204 No Content。

删除 URL 变量

DELETE /hooks/:hook_id/url_variables/:key

支持的属性：

Attribute Type Required Description
hook_id integer 是 系统钩子的 ID。
key string 是 URL 变量的键。

成功时，此端点返回响应代码 204 No Content。