更新时间:2025-07-25 GMT+08:00

配置Webhook

配置Webhook概述

开发人员可在Webhook界面配置第三方系统的URL,并根据项目需求订阅代码托管仓库的分支推送(push)、标签推送(tag push)等事件。当订阅事件发生时,可通过Webhook向第三方系统的URL发送POST请求,用以触发第三方系统的相关操作,例如:触发自己系统(第三方系统)界面的通知弹窗;或触发自己系统(第三方系统)的构建、更新镜像、部署等操作。

在配置合并请求规则前,用户请先查看约束与限制,满足配置权限的用户请根据配置Webhook设置进行配置,示例配置效果请查看相关文档

约束与限制

表1 配置Webhook的约束与限制

限制类别

具体限制

权限设置

当用户角色为“项目经理”或者“项目管理员”,可以设置项目级Webhook,请参考配置项目级的Repo权限配置权限。

功能限制

每个仓库最多只能设置20个Webhook。

配置Webhook设置

Webhook设置位于仓库详情中的 设置 > 服务集成 > Webhook设置。用户可以参考下图填写参数,也可以参考下表填写参数。配置的示例效果请查看相关文档

表2 新建Webhook字段说明

字段

说明

取值样例

名称

可自定义名称,最多200个字符。

Webhook_Test

描述

非必填项。用于描述该Webhook,最多200个字符。

Test

URL

URL及其响应中均不能有敏感数据,如果一定要包含,需用户自行加解密以保证安全性。WebHook URL需第三方CI/CD系统提供。

https://example.com

Token类型

非必填项。当用户想要用于第三方服务Webhook接口鉴权,鉴权信息放在http请求header,作为Key,和下一个参数“Token”结合使用,包含以下三个选项可选:

  • X-Repo-Token
  • X-Gitlab-Token
  • X-Auth-Token

除上述三种用户也可以自定义输入Token类型。

用户在配置Webhook的时候,可以选择设置用户的Token,该Token会与用户的Webhook URL关联,系统会将该Token放在请求头的“X-Repo-Token”字段发送给用户。

X-Repo-Token

Token

非必填项。当用户选择“Token类型”参数后,该参数作为Value,和上一个参数“Token类型”结合使用。

用户自定义输入,最多2000个字符。用于第三方CI/CD系统鉴权,鉴权信息放在http请求header

Token_Test

事件类型

系统可订阅以下事件:

  • 推送事件。勾选后,则需要继续填写“分支过滤正则规则”,长度不能超过500个字符,“.*”表示匹配全部分支,如果分支名称匹配设置的正则,在Repo仓库进行代码更新,例如更新子模块中的代码、在线或本地Git客户端中推送代码均会触发该事件。
  • 合并请求事件。勾选后,更新合并请求的代码、关闭合并请求、重开合并请求、更新合并请求标题或描述、更新合并人、更新工作项、删除源分支或者更新Squash合并,都会触发该事件。
  • Tag推送事件。勾选后,新建或删除Tag均会触发该事件。
  • 评论事件。勾选后,在代码文件中添加检视意见、在提交详情文件变更下添加检视意见、在合并请求文件变更中添加检视意见、在仓库提交详情和在合并请求详情中添加评论会触发该事件。
  • 勾选“推送事件”,设置“分支过滤正则规则”“Branch_*”,表示所有以“Branch_”开头的分支推送都会触发该事件。
  • 勾选合并请求事件。
  • 勾选Tag推送事件。

相关文档

  • 根据上述表格配置后,触发“推送事件”,如下图所示,正常返回“200”。如果代码示例的“Token”值与表格中配置的值不一致,会导致鉴权失败,返回“401”