项目回调钩子 | 帮助文档 - 工蜂合作伙伴版

# 项目回调钩子

如果使用 project_full_path，确保 project_full_path 编码过，例子：/api/v3/projects/tencent/code--> /api/v3/projects/tencent%2Fcode (/ 编码 %2F)

# 给项目增加回调钩子

增加项目回调钩子

POST /api/v3/projects/:id/hooks

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
url	string	回调钩子地址
push_events	boolean (可选)	有推送事件触发回调钩子，默认 `true`
issues_events	boolean (可选)	有议题事件触发回调钩子，默认 `false`
merge_requests_events	boolean (可选)	有合并请求事件触发回调钩子默认 `false`
tag_push_events	boolean (可选)	有 Tag 推送事件触发回调钩子默认 `false`
note_events	boolean (可选)	有评论事件触发回调钩子，默认 `false`
review_events	boolean (可选)	有评审事件触发回调钩子，默认 `false`
git_post_lock_events	boolean (可选)	锁定文件或解锁时，这个钩子将被触发默认 `false`
git_pre_receive_events	boolean (可选)	将会在服务端接受推送前触发默认 `false`
project_setting_events	boolean (可选)	当项目设置变更时，这个钩子将被触发默认 `false`
url_mask_variables	list (可选)	用于隐藏对外展示的 URL 例如：url_mask_variables: [{variable: "123456", mask:"token"} ] variable 需要隐藏的字符，mask 隐藏后对外显示的字符
token	string(可选)	用以校验收到的负载;此 token 不会在包含在返回值中

返回值：

{
    "id": 1,
    "url": "https://git.tencent.com/hook/push",
    "created_at": "2015-03-29T04:48:31+0000",
    "project_id": 2365,
    "push_events": true,
    "issues_events": false,
    "merge_requests_events": false,
    "tag_push_events": false,
    "note_events": false,
    "review_events": false,
    "git_post_lock_events": false,
    "active": true

}

# 编辑项目回调钩子

修改项目中的回调钩子

PUT /api/v3/projects/:id/hooks/:hook_id

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
url	string	回调钩子地址
push_events	boolean（可选）	有推送事件触发回调钩子
issues_events	boolean（可选）	有议题事件触发回调钩子
merge_requests_events	boolean（可选）	有合并请求事件触发回调钩子
tag_push_events	boolean（可选）	有 Tag 推送事件触发回调钩子
note_events	boolean（可选）	有评论事件触发回调钩子
review_events	boolean（可选）	有评审事件触发回调钩子
git_post_lock_events	boolean (可选)	锁定文件或解锁时，这个钩子将被触发默认 `false`
git_pre_receive_events	boolean (可选)	将会在服务端接受推送前触发默认 `false`
project_setting_events	boolean (可选)	当项目设置变更时，这个钩子将被触发默认 `false`
token	string(可选)	用以校验收到的负载;此 token 不会在包含在返回值中

返回值：

{
    "id": 1,
    "url": "https://git.tencent.com/hook/push",
    "created_at": "2015-03-29T04:48:31+0000",
    "project_id": 2365,
    "push_events": false,
    "issues_events": false,
    "merge_requests_events": false,
    "tag_push_events": false,
    "note_events": false,
    "review_events": false,
    "git_post_lock_events": false,
    "active": false
}

# 查询项目单个回调钩子

根据回调钩子 id 查询项目回调钩子

GET /api/v3/projects/:id/hooks/:hook_id

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_id	integer	回调钩子 id

返回值：

{
    "id": 2,
    "url": "https://git.tencent.com/hook/push",
    "created_at": "2015-03-29T04:48:31+0000",
    "project_id": 2,
    "push_events": true,
    "issues_events": false,
    "merge_requests_events": false,
    "tag_push_events": false,
    "note_events": false,
    "review_events": false,
    "git_post_lock_events": false,
    "active": true

}

# 查询项目回调钩子列表

在项目中查询项目回调钩子列表

GET /api/v3/projects/:id/hooks

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
page	integer	分页（默认值：`1`）
per_page	integer	默认页面大小（默认值： `20`，最大值： `100`）

返回值：

[
    {
    "id": 1,
    "url": "https://git.tencent.com/hook/push",
    "created_at": "2015-03-29T04:48:31+0000",
    "project_id": 2,
    "push_events": false,
    "issues_events": false,
    "merge_requests_events": false,
    "tag_push_events": false,
    "note_events": false,
    "review_events": false,
    "git_post_lock_events": false,
    "active": true

}
]

# 删除项目回调钩子

在项目中删除某个指定的回调钩子

DELETE /api/v3/projects/:id/hooks/:hook_id

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_id	integer	回调钩子 id

返回值：

200 或相关状态码

# 回调钩子发送历史

# 查询项目回调钩子发送历史列表

在项目中查询某个指定的回调钩子发送历史列表

GET /api/v3/projects/:id/hooks/:hook_id/logs

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_id	integer	回调钩子 id
response_status	string（可选）	响应状态，可选`success`, `error`（默认全选）
created_after	yyyy-MM-dd'T'HH`:`mm`:`ssZ（可选）	返回给定时间及之后新增的发送历史；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”）
created_before	yyyy-MM-dd'T'HH`:`mm`:`ssZ（可选）	返回给定时间及之前新增的发送历史；例如 2019-03-25T00:10:19+0000 或 2019-03-25T00:10:19+0800，时间参数必须转码，如“2019-03-25T00:10:19%2B0800”）
order_by	integer（可选）	排序字段:`created_at`
sort	string（可选）	排序方式，允许`asc`,`desc`（默认`desc`）
page	integer（可选）	页数（默认值：1）
per_page	integer（可选）	默认页面大小（默认值：20，最大值：100）

返回值：

[
    {
        "id": 28470,
        "web_hook_id": 1008,
        "url": "https://www.xxx.com",
        "trigger": "Push Hook",
        "request_headers": "{\"X-Gitlab-Event\":\"Push Hook\",\"X-Event\":\"Push Hook\",\"X-Token\":null,\"X-TRACE-ID\":\"18cabc8d45-ac32242ce3b8404488c24b082ca09549\",\"X-Gitlab-Token\":null}",
        "request_data": "{\"object_kind\":\"push\",\"operation_kind\":\"update\",\"action_kind\":\"modify file\",\"before\":\"9e48389fe6406438858112cabce8180b45dfc3f0\",\"after\":\"ef27fcc4203be34375d98be6bb52f642281ab181\",\"ref\":\"refs/heads/master\",\"checkout_sha\":\"ef27fcc4203be34375d98be6bb52f642281ab181\",\"user_name\":\"git_user1\",\"user_id\":11323,\"user_email\":\"git_user1@tencent.com\",\"project_id\":9861,\"repository\":{\"name\":\"hook\",\"description\":\"\",\"homepage\":\"https://git.tencent.com/TEST_TO.O_/hook\",\"git_http_url\":\"https://git.tencent.com/TEST_TO.O_/hook.git\",\"git_ssh_url\":\"git@git.tencent.com:TEST_TO.O_/hook.git\",\"url\":\"git@git.tencent.com:TEST_TO.O_/hook.git\",\"visibility_level\":10},\"commits\":[{\"id\":\"ef27fcc4403be34375d98be6bb52f642281ab181\",\"message\":\"wewef \",\"timestamp\":\"2020-04-02T07:00:06+0000\",\"url\":\"https://git.tencent.com/TEST_TO.O_/hook/commit/ef27fcc4403be34375d98be6bb52f642281ab181\",\"author\":{\"name\":\"git_user1\",\"email\":\"git_user1@tencent.com\"},\"added\":[],\"modified\":[\"aa\"],\"removed\":[]}],\"total_commits_count\":1}",
        "response_headers": null,
        "response_body": null,
        "response_status": "error",
        "execution_duration": 1521,
        "internal_error_message": "I/O error on POST request for \"https://www.xxx.com\": connect timed out; nested exception is java.net.SocketTimeoutException: connect timed out",
        "created_at": "2020-04-02T07:47:44+0000",
        "updated_at": "2020-04-02T07:47:44+0000"
    }
]

# 查询项目回调钩子中指定的发送历史

在项目中查询某个回调钩子中指定的发送历史

GET /api/v3/projects/:id/hooks/:hook_id/logs/:hook_log_id

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_id	integer	回调钩子 id
hook_log_id	integer	回调钩子发送历史的 id

返回值：

[
    {
        "id": 28470,
        "web_hook_id": 1008,
        "url": "https://www.xxx.com",
        "trigger": "Push Hook",
        "request_headers": "{\"X-Gitlab-Event\":\"Push Hook\",\"X-Event\":\"Push Hook\",\"X-Token\":null,\"X-TRACE-ID\":\"18cabc8d45-ac32242ce3b8404488c24b082ca09549\",\"X-Gitlab-Token\":null}",
        "request_data": "{\"object_kind\":\"push\",\"operation_kind\":\"update\",\"action_kind\":\"modify file\",\"before\":\"9e48389fe6406438858112cabce8180b45dfc3f0\",\"after\":\"ef27fcc4203be34375d98be6bb52f642281ab181\",\"ref\":\"refs/heads/master\",\"checkout_sha\":\"ef27fcc4203be34375d98be6bb52f642281ab181\",\"user_name\":\"git_user1\",\"user_id\":11323,\"user_email\":\"git_user1@tencent.com\",\"project_id\":9861,\"repository\":{\"name\":\"hook\",\"description\":\"\",\"homepage\":\"https://git.tencent.com/TEST_TO.O_/hook\",\"git_http_url\":\"https://git.tencent.com/TEST_TO.O_/hook.git\",\"git_ssh_url\":\"git@git.tencent.com:TEST_TO.O_/hook.git\",\"url\":\"git@git.tencent.com:TEST_TO.O_/hook.git\",\"visibility_level\":10},\"commits\":[{\"id\":\"ef27fcc4403be34375d98be6bb52f642281ab181\",\"message\":\"wewef \",\"timestamp\":\"2020-04-02T07:00:06+0000\",\"url\":\"https://git.tencent.com/TEST_TO.O_/hook/commit/ef27fcc4403be34375d98be6bb52f642281ab181\",\"author\":{\"name\":\"git_user1\",\"email\":\"git_user1@tencent.com\"},\"added\":[],\"modified\":[\"aa\"],\"removed\":[]}],\"total_commits_count\":1}",
        "response_headers": null,
        "response_body": null,
        "response_status": "error",
        "execution_duration": 1521.0,
        "internal_error_message": "I/O error on POST request for \"https://www.xxx.com\": connect timed out; nested exception is java.net.SocketTimeoutException: connect timed out",
        "created_at": "2020-04-02T07:47:44+0000",
        "updated_at": "2020-04-02T07:47:44+0000"
    }
]

# 重放项目回调钩子中指定的发送历史

在项目中重放某个回调钩子中指定的发送历史

POST /api/v3/projects/:id/hooks/:hook_id/logs/:hook_log_id/retry

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_id	integer	回调钩子 id
hook_log_id	integer	回调钩子发送历史的 id

返回值：

200 或相关状态码

# 激活回调钩子

# 激活项目回调钩子

在项目中激活某个回调钩子

POST /api/v3/projects/:id/hooks/:hook_id/activate

参数：

参数	类型	描述
id	integer 或 string	项目 ID 或项目全路径 project_full_path
hook_id	integer	回调钩子 id

返回值：

true 或 false

# Pre-receive 脚本

# 查询 Pre-receive 脚本模板

查询仓库中的 Pre-receive 脚本模板

GET /api/v3/projects/:id/pre_hooks

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_names	array of string (可选)	pre-receive 脚本模板名称，可选值：`check-linear-history.sh`,`check-msg-epc.sh`,`require-issue-multiline.sh`或`require-issue.sh`

返回值：

[
    {
        "hook_name": "check-linear-history.sh",
        "introduction": "A server-side hook that checks if the commit record is submitted linearly.",
        "content": "#!/bin/sh\n#\n# check commit for linear history\n\n# for test, please add the newrev and oldrev sha1 values, and put the shell in the root directory of the git project, execute the shell, you can verify\n#oldrev=\"c4881d580a89623c192cc94bd62d6bc4e3332dbd\"\n#newrev=\"9c5484273d254b1975a84b494ce062a1516a5808\"\n#PARAM_BRANCH=\"master\"\n\nrefname=$PARAM_BRANCH\nREGEX=$PARAM_REGEX\n\nexport PATH=$PATH:$GIT_PATH\nzero_commit=\"0000000000000000000000000000000000000000\"\n\n# if null, set default regex and response message\nif [ ! -n \"$REGEX\" ]; then\n    REGEX=\"(^dev$|^(feature|hotfix)-[^\\s]+$)\"\nfi\n\nif [[ $oldrev == $zero_commit || $newrev == $zero_commit ]]; then\n\texit 0\nfi\n\nif echo $refname | grep -iqE \"$REGEX\"; then\n  merge_bases=`git merge-base $oldrev $newrev`\n  if [ \"$merge_bases\" != \"$oldrev\" ]\n  then\n    echo \"Non fastward is disallowed\"\n    exit 1\n  fi\n  # non-fast-forward case:\n  git rev-list --parents $merge_bases..$newrev \\\n    | while read x; do\n      set -- $x\n      if [ \"$#\" != \"2\" ]\n      then\n        echo \"Multiple parents is disallowed: $x\";\n        exit 1\n      fi;\n    done\n  [ $? -ne 0 ] && exit 1\nfi\nexit 0",
        "params": {
            "PARAM_REGEX": "(^dev$|^(feature|hotfix)-[^s]+$)"
        }
    }
    
]

# 查询项目中已配置的 Pre-receive 脚本

查询项目中已经配置过的 Pre-receive 脚本

GET /api/v3/projects/:id/pre_hooks/list

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_names	array of string (可选)	pre-receive 脚本模板名称，可选值：`check-linear-history.sh`,`check-msg-epc.sh`,`require-issue-multiline.sh`或`require-issue.sh`

返回值：

[
    {
        "hook_name": "check-linear-history.sh",
        "introduction": "A server-side hook that checks if the commit record is submitted linearly.",
        "content": "#!/bin/sh\n#\n# check commit for linear history\n\n# for test, please add the newrev and oldrev sha1 values, and put the shell in the root directory of the git project, execute the shell, you can verify\n#oldrev=\"c4881d580a89623c192cc94bd62d6bc4e3332dbd\"\n#newrev=\"9c5484273d254b1975a84b494ce062a1516a5808\"\n#PARAM_BRANCH=\"master\"\n\nrefname=$PARAM_BRANCH\nREGEX=$PARAM_REGEX\n\nexport PATH=$PATH:$GIT_PATH\nzero_commit=\"0000000000000000000000000000000000000000\"\n\n# if null, set default regex and response message\nif [ ! -n \"$REGEX\" ]; then\n    REGEX=\"(^dev$|^(feature|hotfix)-[^\\s]+$)\"\nfi\n\nif [[ $oldrev == $zero_commit || $newrev == $zero_commit ]]; then\n\texit 0\nfi\n\nif echo $refname | grep -iqE \"$REGEX\"; then\n  merge_bases=`git merge-base $oldrev $newrev`\n  if [ \"$merge_bases\" != \"$oldrev\" ]\n  then\n    echo \"Non fastward is disallowed\"\n    exit 1\n  fi\n  # non-fast-forward case:\n  git rev-list --parents $merge_bases..$newrev \\\n    | while read x; do\n      set -- $x\n      if [ \"$#\" != \"2\" ]\n      then\n        echo \"Multiple parents is disallowed: $x\";\n        exit 1\n      fi;\n    done\n  [ $? -ne 0 ] && exit 1\nfi\nexit 0",
        "params": {
            "PARAM_REGEX": "(^dev$|^(feature|hotfix)-[^s]+$)"
        }
    }
    

]

# 创建 Pre-receive 脚本

创建 Pre-receive 脚本

POST /api/v3/projects/:id/pre_hooks

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_name	string	Pre-receive 脚本模板名称

若需要配置钩子的参数 (params)，请将参数以 json 的格式放置在 request 请求体中，默认使用模板设置的参数。
注意参数名只能为模板中已有的。例如，hook_name 为 require-issue-multiline.sh，其对应模板中的 params 为

{ "PARAM_REGEX": "(--bug=|--story=|--task=|--test=|--other=|Merge)", "PARAM_ERROR_MSG": "the commit message only accept:--bug=tapdId or --story=tapdId or --task=tapdId or --test=testId or --other=some message" }
则参数的 key 只能从 (PARAM_REGEX、PARAM_ERROR_MSG) 中进行选择，例如{"PARAM_REGEX": "abc"}

返回值：

{
    "id": 1007428,
    "url": "require-issue-multiline.sh",
    "serviceId": null,
    "projectId": 6368,
    "type": "PreReceiveHook",
    "pushEvents": true,
    "issuesEvents": false,
    "tagPushEvents": false,
    "noteEvents": false,
    "mergeRequestsEvents": false,
    "reviewEvents": false,
    "enableSslVerification": true,
    "param": "{\"PARAM_REGEX\":\"(--bug=|--story=|--task=|--test=|--other=|Merge)\",\"PARAM_ERROR_MSG\":\"the commit message only accept:--bug=tapdId or --story=tapdId or --task=tapdId or --test=testId or --other=some message\"}",
    "timeout": 60000,
    "createdAt": 1628755335865,
    "updatedAt": 1628755335865,
    "encryptedToken": null,
    "active": true,
    "enableSslVerificationDescription": "enable"
}

# 更新 Pre-receive 脚本

更新 Pre-receive 脚本

PUT /api/v3/projects/:id/pre_hooks/:hook_id

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_id	integer	对应的 id

若需要更新的参数 (params)，请将参数以 json 的格式放置在 request 请求体中。
注意参数名只能为模板中已有的。例如，hook_name 为 require-issue-multiline.sh，其对应模板中的 params 为

{ "PARAM_REGEX": "(--bug=|--story=|--task=|--test=|--other=|Merge)", "PARAM_ERROR_MSG": "the commit message only accept:--bug=tapdId or --story=tapdId or --task=tapdId or --test=testId or --other=some message" }
则参数的 key 只能从 (PARAM_REGEX、PARAM_ERROR_MSG) 中进行选择，例如{"PARAM_REGEX": "abc"}

返回值：

{
    "id": 1007428,
    "url": "require-issue-multiline.sh",
    "serviceId": null,
    "projectId": 6368,
    "type": "PreReceiveHook",
    "pushEvents": true,
    "issuesEvents": false,
    "tagPushEvents": false,
    "noteEvents": false,
    "mergeRequestsEvents": false,
    "reviewEvents": false,
    "enableSslVerification": true,
    "param": "{\"PARAM_REGEX\":\"abc\"}",
    "timeout": 60000,
    "createdAt": 1628755336000,
    "updatedAt": 1628755336000,
    "encryptedToken": null,
    "active": true,
    "enableSslVerificationDescription": "enable"
}

# 删除 Pre-receive 脚本

删除 Pre-receive 脚本

DELETE /api/v3/projects/:id/pre_hooks/:hook_id

参数：

参数	类型	描述
id	integer or string	项目 ID 或项目全路径 project_full_path
hook_id	integer	对应的 id

返回值：

"success"

← 提交检测合并请求 (MR) →