系统勾子 API

Tier: 基础版, 专业版, 旗舰版
Offering: 私有化部署

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

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

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

阅读更多关于系统钩子。

列出系统钩子#

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

plaintext
GET /hooks

示例请求：

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/hooks"

示例响应：

json
1[
2  {
3    "id":1,
4    "url":"https://gitlab.example.com/hook",
5    "name": "Hook name",
6    "description": "Hook description",
7    "created_at":"2016-10-31T12:32:15.192Z",
8    "push_events":true,
9    "tag_push_events":false,
10    "merge_requests_events": true,
11    "repository_update_events": true,
12    "enable_ssl_verification":true,
13    "url_variables": []
14  }
15]

获取系统钩子#

通过其 ID 获取系统钩子。

plaintext
GET /hooks/:id

属性	类型	必需	描述
id	integer	yes	钩子的 ID

示例请求：

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

示例响应：

json
1{
2  "id": 1,
3  "url": "https://gitlab.example.com/hook",
4  "name": "Hook name",
5  "description": "Hook description",
6  "created_at": "2016-10-31T12:32:15.192Z",
7  "push_events": true,
8  "tag_push_events": false,
9  "merge_requests_events": true,
10  "repository_update_events": true,
11  "enable_ssl_verification": true,
12  "url_variables": []
13}

添加新系统钩子#

添加一个新的系统钩子。

plaintext
POST /hooks

属性	类型	必需	描述
url	string	yes	钩子的 URL
name	string	no	钩子的名称（在 GitLab 17.1 中引入）
description	string	no	钩子的描述（在 GitLab 17.1 中引入）
token	string	no	用于验证接收到的负载的密钥，这不会在响应中返回
push_events	boolean	no	当为 true 时，钩子会在推送事件上触发
tag_push_events	boolean	no	当为 true 时，钩子会在新的标签被推送时触发
merge_requests_events	boolean	no	在合并请求事件上触发钩子
repository_update_events	boolean	no	在仓库更新事件上触发钩子
enable_ssl_verification	boolean	no	触发钩子时进行 SSL 验证
push_events_branch_filter	string	no	仅在匹配的分支上触发推送事件的钩子
branch_filter_strategy	string	no	按分支过滤推送事件。可能的值为 wildcard（默认），regex 和 all_branches

示例请求：

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

示例响应：

json
1[
2  {
3    "id":1,
4    "url":"https://gitlab.example.com/hook",
5    "name": "Hook name",
6    "description": "Hook description",
7    "created_at":"2016-10-31T12:32:15.192Z",
8    "push_events":true,
9    "tag_push_events":false,
10    "merge_requests_events": true,
11    "repository_update_events": true,
12    "enable_ssl_verification":true,
13    "url_variables": []
14  }
15]

更新系统钩子#

更新现有的系统钩子。

plaintext
PUT /hooks/:hook_id

属性	类型	必需	描述
hook_id	integer	Yes	系统钩子的 ID
url	string	no	钩子的 URL
token	string	no	用于验证接收到的负载的密钥，这不会在响应中返回
push_events	boolean	no	当为 true 时，钩子会在推送事件上触发
tag_push_events	boolean	no	当为 true 时，钩子会在新的标签被推送时触发
merge_requests_events	boolean	no	在合并请求事件上触发钩子
repository_update_events	boolean	no	在仓库更新事件上触发钩子
enable_ssl_verification	boolean	no	触发钩子时进行 SSL 验证
push_events_branch_filter	string	no	仅在匹配的分支上触发推送事件的钩子
branch_filter_strategy	string	no	按分支过滤推送事件。可能的值为 wildcard（默认），regex 和 all_branches

测试系统钩子#

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

plaintext
POST /hooks/:id

属性	类型	必需	描述
id	integer	yes	钩子的 ID

示例请求：

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

响应始终是模拟数据：

json
1{
2   "project_id" : 1,
3   "owner_email" : "example@gitlabhq.com",
4   "owner_name" : "Someone",
5   "name" : "Ruby",
6   "path" : "ruby",
7   "event_name" : "project_create"
8}

删除系统钩子#

删除一个系统钩子。

plaintext
DELETE /hooks/:id

属性	类型	必需	描述
id	integer	yes	钩子的 ID

示例请求：

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

设置 URL 变量#

History

在 GitLab 15.2 中引入。

plaintext
PUT /hooks/:hook_id/url_variables/:key

支持的属性：

属性	类型	必需	描述
hook_id	integer	Yes	系统钩子的 ID。
key	string	Yes	URL 变量的键。
value	string	Yes	URL 变量的值。

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

删除 URL 变量#

History

在 GitLab 15.2 中引入。

plaintext
DELETE /hooks/:hook_id/url_variables/:key

支持的属性：

属性	类型	必需	描述
hook_id	integer	Yes	系统钩子的 ID。
key	string	Yes	URL 变量的键。

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