gitea-docs/i18n/zh-cn/docusaurus-plugin-content-docs/current/usage/repository/webhooks.md

date, slug, sidebar_position, aliases

date	slug	sidebar_position	aliases
2016-12-01T16:00:00+02:00	webhooks	30	/zh-cn/webhooks

Webhooks

Gitea 可以为仓库活动发送出站 Webhook。仓库级 Webhook 由仓库管理员在 /:username/:reponame/settings/hooks 中配置。组织、用户和系统管理级别 也有对应的 Webhook 配置页面。

Webhook 配置支持四种作用域：

• 仓库 Webhook：仅对单个仓库中的活动触发。
• 组织 Webhook：对该组织拥有的仓库中的活动触发。
• 用户 Webhook：对该用户拥有的仓库中的活动触发。
• 系统 Webhook：对实例中的所有符合条件的活动触发。

Gitea 还支持由管理员定义的 默认 Webhook。它并不是额外的投递作用域， 而是会在新仓库创建时被复制到仓库中，之后按普通仓库 Webhook 的方式工作。

Gitea 支持以下出站 Webhook 集成：

• Gitea
• Gogs
• Slack
• Discord
• Dingtalk
• Telegram
• Microsoft Teams
• Feishu
• Matrix
• Wechatwork
• Packagist

Gitea 和 Gogs 类型会发送通用 Webhook 负载。上面列出的聊天和服务集成 会将同一个内部事件转换为各自服务所需的请求体格式。

本页分为三个部分：

• 配置：如何配置 Webhook 设置，例如 URL、密钥、分支过滤器和授权头。
• 投递：Gitea 如何发送 Webhook 请求、会携带哪些请求头，以及如何校验投递。
• 事件：Gitea 会投递哪些事件，以及每个事件包含哪些顶层 payload 参数。

配置

本节介绍在创建或编辑 Webhook 时可以设置的选项。

配置 Webhook

创建 Webhook 时，主要配置项包括：

• Target URL：接收投递的目标地址。
• HTTP Method：通用 Webhook 通常使用 POST。
• POST Content Type：通用 Webhook 可使用 application/json 或 application/x-www-form-urlencoded。
• Secret：用于对原始请求体进行 HMAC 签名。
• Authorization Header：可选的自定义 Authorization 请求头，会随每次请求发送。
• Branch Filter：可选的分支或标签过滤规则。
• Trigger On：Push Events、All Events 或自定义事件选择。
• Active：是否启用该 Webhook。

:::note 旧示例里可能仍会在 JSON payload 中看到 secret 字段。当前版本的 Gitea 不会再把 Webhook 密钥放进 payload 正文中。请始终通过签名请求头来验证请求。 :::

分支过滤器

分支过滤器使用与 github.com/gobwas/glob 兼容的 glob 语法。

• 空值、* 或 ** 表示匹配全部。
• 像 main 这样的普通分支名会匹配该分支。
• 也支持 refs/tags/v* 这样的完整 ref。
• 支持 {main,release/*} 这样的花括号表达式。
• 过滤器只对带 git ref 的事件生效，例如 create、delete 和 push。
• 不带 ref 的事件，例如 issue 或 release，会忽略分支过滤器。

示例：

• main
• {main,feature/*}
• {refs/heads/feature/*,refs/tags/release/*}

授权头

Gitea 可以配置为在每次 Webhook 投递时发送自定义 Authorization header。 它与 Webhook 密钥是相互独立的：

• 使用密钥通过 HMAC 校验请求完整性。
• 当接收端需要应用层认证时，使用 Authorization 请求头。

投递

本节说明 Gitea 如何发送 Webhook 投递，以及接收端如何识别和验证这些请求。

投递行为

• Webhook 会通过 HTTP 异步投递。
• 通用 Gitea 和 Gogs Webhook 支持 POST 与 GET；通常应使用 POST。
• 对于 POST 请求，payload 可以直接作为 JSON （application/json）发送，也可以放在名为 payload 的表单字段中 （application/x-www-form-urlencoded）。
• 某些特定服务的集成可能会使用该服务要求的 HTTP 方法和请求体格式。

投递请求头

每次投递都包含唯一的 delivery ID 和事件请求头。对于兼容 GitHub 的集成， Gitea 也会同时发送对应的 GitHub 和 Gogs 风格请求头。

请求头	说明
X-Gitea-Delivery	本次投递尝试的唯一 UUID。
X-Gitea-Event	规范化事件名，例如 push、issues 或 pull_request。
X-Gitea-Event-Type	更具体的事件类型，例如 issue_assign 或 pull_request_review_comment。
X-Gitea-Signature	原始请求体的十六进制 HMAC-SHA256 值，不带前缀。
X-Gitea-Hook-Installation-Target-Type	Webhook 定义所在范围，通常是 repository、organization、user 或 system。默认 Webhook 会先复制到仓库后再投递，因此通常会表现为 repository。
X-Gogs-Delivery、X-Gogs-Event、X-Gogs-Event-Type、X-Gogs-Signature	与 Gitea 对应请求头值相同的兼容请求头。
X-GitHub-Delivery、X-GitHub-Event、X-GitHub-Event-Type	GitHub 风格兼容请求头。
X-GitHub-Hook-Installation-Target-Type	GitHub 风格的 Webhook 作用域请求头。
X-Hub-Signature	GitHub 兼容的 HMAC-SHA1 请求头，格式为 sha1=<digest>。
X-Hub-Signature-256	GitHub 兼容的 HMAC-SHA256 请求头，格式为 sha256=<digest>。

如果未配置密钥，签名请求头仍然会存在，但摘要值为空。

Event 与 Event-Type

某些 Gitea Webhook 订阅会被归类到同一个规范化事件名下。例如，issue 指派 投递会归类到 issue 事件组：

X-Gitea-Event: issues
X-Gitea-Event-Type: issue_assign
X-GitHub-Event: issues
X-GitHub-Event-Type: issue_assign

如果你需要知道真正触发投递的具体事件类型，请使用 X-Gitea-Event-Type。

校验投递

Gitea 会使用你的 Webhook 密钥对原始请求体进行签名。要校验一次投递：

1. 按接收到的原始内容读取请求体。
2. 使用 Webhook 密钥计算 HMAC-SHA256 摘要。
3. 将结果与 X-Gitea-Signature 或 GitHub 兼容的 X-Hub-Signature-256 进行比较。
4. 尽量使用常量时间比较函数。

注意事项：

• X-Gitea-Signature 仅包含小写十六进制的 SHA-256 摘要。
• X-Hub-Signature-256 使用相同摘要，但带有 sha256= 前缀。
• X-Hub-Signature 也会出于兼容性目的发送，其算法是 SHA-1。
• 在完成签名校验之前，不应先解析 JSON 或修改请求体。

PHP 示例

下面的示例演示如何校验以 application/json 发送的通用 Gitea Webhook。

<?php

$secret = '123';

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Only POST is allowed');
}

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';

if ($payload === false || $signature === '') {
    http_response_code(400);
    exit('Missing payload or signature');
}

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
$data = json_decode($payload, true);

if (!is_array($data)) {
    http_response_code(400);
    exit('Invalid JSON payload');
}

http_response_code(204);

事件

本节采用与 GitHub Webhook 文档类似的按事件逐项描述方式：每个事件都会说明 其触发时机，以及 payload 中包含哪些顶层字段。

事件分组与 Webhook 设置界面中的分组一致：Repository Events、 Issue Events、Pull Request Events 和 Workflow Events。

仓库事件

• create、delete、fork、push、wiki、repository、release、package、status

create

当分支或标签被创建时，会触发此事件。

Payload 参数

名称	类型	说明
sha	string	必填。 新建引用对应的对象 ID。
ref	string	必填。 被创建的分支名或标签名。
ref_type	string	必填。 引用类型，例如 branch 或 tag。
repository	object	必填。 创建该引用的仓库。
sender	object	必填。 创建该引用的用户。

delete

当分支或标签被删除时，会触发此事件。

Payload 参数

名称	类型	说明
ref	string	必填。 被删除的分支名或标签名。
ref_type	string	必填。 引用类型，例如 branch 或 tag。
pusher_type	string	必填。 删除该 ref 的行为主体类型。当前 Gitea payload 中使用 user。
repository	object	必填。 删除该引用所在的仓库。
sender	object	必填。 删除该引用的用户。

fork

当仓库被 fork 时，会触发此事件。

Payload 参数

名称	类型	说明
forkee	object	必填。 新创建的 fork 仓库。
repository	object	必填。 被 fork 的原始仓库。
sender	object	必填。 创建 fork 的用户。

push

当提交被推送到某个分支或标签时，会触发此事件。

Payload 参数

名称	类型	说明
ref	string	必填。 被推送的完整 ref，例如 refs/heads/main。
before	string	必填。 推送前的提交 SHA。
after	string	必填。 推送后的提交 SHA。
compare_url	string	必填。 用于比较 before 和 after 的 URL。
commits	array	必填。 本次推送包含的提交列表。
total_commits	integer	必填。 本次推送中的提交数量。
head_commit	object	本次推送中的最新提交。
repository	object	必填。 接收此次推送的仓库。
pusher	object	必填。 执行推送的用户。
sender	object	必填。 触发 Webhook 的用户。

wiki

当 Wiki 页面被创建、编辑或删除时，会触发此事件。

动作类型： created、edited、deleted

Payload 参数

名称	类型	说明
action	string	必填。 Wiki 页面操作类型。
repository	object	必填。 拥有该 Wiki 的仓库。
sender	object	必填。 修改 Wiki 页面的用户。
page	string	必填。 Wiki 页面名称。
comment	string	Wiki 提交信息或备注。

repository

当仓库被创建或删除时，会触发此事件。

动作类型： created、deleted

Payload 参数

名称	类型	说明
action	string	必填。 仓库操作类型。
repository	object	必填。 被创建或删除的仓库。
organization	object	当仓库属于某个组织时会出现。
sender	object	必填。 执行该操作的用户。

release

当发布版本被发布、更新或删除时，会触发此事件。

动作类型： published、updated、deleted

Payload 参数

名称	类型	说明
action	string	必填。 Release 操作类型。
release	object	必填。 被操作的发布版本。
repository	object	必填。 包含该发布版本的仓库。
sender	object	必填。 执行该操作的用户。

package

当包被创建或删除时，会触发此事件。

动作类型： created、deleted

Payload 参数

名称	类型	说明
action	string	必填。 包操作类型。
repository	object	与该包关联的仓库；如果适用则会出现。
package	object	必填。 被操作的包。
organization	object	当包所有者是组织时会出现。
sender	object	必填。 执行该操作的用户。

status

当通过 API 创建或更新提交状态时，会触发此事件。

Payload 参数

名称	类型	说明
commit	object	与该状态关联的提交。
context	string	必填。 状态上下文，例如 ci/build。
created_at	string	必填。 状态创建时间。
description	string	状态描述文本。
id	integer	必填。 状态标识符。
repository	object	必填。 包含该提交的仓库。
sender	object	必填。 创建该状态的用户。
sha	string	必填。 提交 SHA。
state	string	必填。 状态值，例如 pending、success、error 或 failure。
target_url	string	与该状态关联的目标 URL。
updated_at	string	状态最后更新时间。

与多数其他 payload 不同，此事件不使用 action 字段，状态变化通过 state 字段表示。

议题事件

• issues、issue_assign、issue_label、issue_milestone、issue_comment

issues

当 issue 被打开、关闭、重新打开、编辑或删除时，会触发此事件。

动作类型： opened、closed、reopened、edited、deleted

Payload 参数

名称	类型	说明
action	string	必填。 Issue 操作类型。
number	integer	必填。 Issue 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
issue	object	必填。 被操作的 issue。
repository	object	必填。 包含该 issue 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 issue 操作关联的提交 SHA；如果适用则会出现。

issue_assign

当 issue 被指派或取消指派时，会触发此事件。

动作类型： assigned、unassigned

Payload 参数

名称	类型	说明
action	string	必填。 指派操作类型。
number	integer	必填。 Issue 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
issue	object	必填。 被操作的 issue。
repository	object	必填。 包含该 issue 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 issue 操作关联的提交 SHA；如果适用则会出现。

issue_label

当 issue 标签被更新或清空时，会触发此事件。

动作类型： label_updated、label_cleared

Payload 参数

名称	类型	说明
action	string	必填。 标签更新操作类型。
number	integer	必填。 Issue 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
issue	object	必填。 被操作的 issue。
repository	object	必填。 包含该 issue 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 issue 操作关联的提交 SHA；如果适用则会出现。

issue_milestone

当 issue 被设置里程碑或移除里程碑时，会触发此事件。

动作类型： milestoned、demilestoned

Payload 参数

名称	类型	说明
action	string	必填。 里程碑操作类型。
number	integer	必填。 Issue 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
issue	object	必填。 被操作的 issue。
repository	object	必填。 包含该 issue 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 issue 操作关联的提交 SHA；如果适用则会出现。

issue_comment

当 issue 评论被创建、编辑或删除时，会触发此事件。

动作类型： created、edited、deleted

Payload 参数

名称	类型	说明
action	string	必填。 评论操作类型。
issue	object	必填。 该评论所属的 issue。
pull_request	object	当该评论位于 pull request 时间线上时会出现。
comment	object	必填。 被创建、编辑或删除的评论。
changes	object	可选。当操作类型为 edited 时，表示评论正文的旧值。
repository	object	必填。 包含该 issue 的仓库。
sender	object	必填。 执行该操作的用户。
is_pull	boolean	必填。 该评论是否位于 pull request 时间线上。

Pull Request 事件

• pull_request、pull_request_assign、pull_request_label、pull_request_milestone、pull_request_comment、pull_request_review、pull_request_review_approved、pull_request_review_rejected、pull_request_review_comment、pull_request_sync、pull_request_review_request

pull_request

当 pull request 被打开、关闭、重新打开、编辑或删除时，会触发此事件。

动作类型： opened、closed、reopened、edited、deleted

Payload 参数

名称	类型	说明
action	string	必填。 Pull request 操作类型。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被操作的 pull request。
requested_reviewer	object	在评审请求事件中会出现。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 pull request 操作关联的提交 SHA；如果适用则会出现。
review	object	在 pull request review 事件中会出现。

pull_request_assign

当 pull request 被指派或取消指派时，会触发此事件。

动作类型： assigned、unassigned

Payload 参数

名称	类型	说明
action	string	必填。 指派操作类型。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被操作的 pull request。
requested_reviewer	object	在评审请求事件中会出现。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 pull request 操作关联的提交 SHA；如果适用则会出现。
review	object	在 pull request review 事件中会出现。

pull_request_label

当 pull request 标签被更新或清空时，会触发此事件。

动作类型： label_updated、label_cleared

Payload 参数

名称	类型	说明
action	string	必填。 标签更新操作类型。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被操作的 pull request。
requested_reviewer	object	在评审请求事件中会出现。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 pull request 操作关联的提交 SHA；如果适用则会出现。
review	object	在 pull request review 事件中会出现。

pull_request_milestone

当 pull request 被设置里程碑或移除里程碑时，会触发此事件。

动作类型： milestoned、demilestoned

Payload 参数

名称	类型	说明
action	string	必填。 里程碑操作类型。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被操作的 pull request。
requested_reviewer	object	在评审请求事件中会出现。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 pull request 操作关联的提交 SHA；如果适用则会出现。
review	object	在 pull request review 事件中会出现。

pull_request_comment

当 pull request 时间线评论被创建、编辑或删除时，会触发此事件。

动作类型： created、edited、deleted

Payload 参数

名称	类型	说明
action	string	必填。 评论操作类型。
issue	object	必填。 与该 pull request 关联的 issue 记录。
pull_request	object	必填。 评论所属的 pull request。
comment	object	必填。 被创建、编辑或删除的评论。
changes	object	可选。当操作类型为 edited 时，表示评论正文的旧值。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 执行该操作的用户。
is_pull	boolean	必填。 对此事件来说始终为 true。

pull_request_review

这是 Webhook 设置界面中的一个仅用于订阅的汇总事件。

它不会生成独立的投递 payload。勾选后，Gitea 实际投递的是更具体的 pull_request_review_approved、pull_request_review_rejected 和 pull_request_review_comment 事件。

pull_request_review_approved

当 pull request review 以批准形式提交时，会触发此事件。

动作类型： reviewed

Payload 参数

名称	类型	说明
action	string	必填。 始终为 reviewed。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被评审的 pull request。
requested_reviewer	object	在评审请求事件中会出现。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 提交该评审的用户。
commit_id	string	与该评审事件关联的提交 SHA；如果适用则会出现。
review	object	必填。 评审负载。对此事件，review.type 为 approved。

pull_request_review_rejected

当 pull request review 以拒绝或请求修改的形式提交时，会触发此事件。

动作类型： reviewed

Payload 参数

名称	类型	说明
action	string	必填。 始终为 reviewed。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被评审的 pull request。
requested_reviewer	object	在评审请求事件中会出现。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 提交该评审的用户。
commit_id	string	与该评审事件关联的提交 SHA；如果适用则会出现。
review	object	必填。 评审负载。对此事件，review.type 为 rejected。

pull_request_review_comment

当 pull request review 以评论形式提交时，会触发此事件。

动作类型： reviewed

Payload 参数

名称	类型	说明
action	string	必填。 始终为 reviewed。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被评审的 pull request。
requested_reviewer	object	在评审请求事件中会出现。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 提交该评审的用户。
commit_id	string	与该评审事件关联的提交 SHA；如果适用则会出现。
review	object	必填。 评审负载。对此事件，review.type 为 comment。

pull_request_sync

当新的提交被推送后，pull request 被同步时，会触发此事件。

动作类型： synchronized

Payload 参数

名称	类型	说明
action	string	必填。 始终为 synchronized。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被同步的 pull request。
requested_reviewer	object	在评审请求事件中会出现。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 执行同步操作的用户。
commit_id	string	与该同步事件关联的提交 SHA；如果适用则会出现。
review	object	在 pull request review 事件中会出现。

pull_request_review_request

当请求审查者或移除审查请求时，会触发此事件。

动作类型： review_requested、review_request_removed

Payload 参数

名称	类型	说明
action	string	必填。 评审请求操作类型。
number	integer	必填。 Pull request 编号。
changes	object	可选。编辑字段之前的值，或标签变化明细。
pull_request	object	必填。 被操作的 pull request。
requested_reviewer	object	被请求或被移除的评审者。
repository	object	必填。 包含该 pull request 的仓库。
sender	object	必填。 执行该操作的用户。
commit_id	string	与该 pull request 操作关联的提交 SHA；如果适用则会出现。
review	object	在 pull request review 事件中会出现。

工作流事件

• workflow_run、workflow_job

workflow_run

当 Gitea Actions 工作流运行状态发生变化时，会触发此事件。

动作类型： queued、waiting、in_progress、completed

Payload 参数

名称	类型	说明
action	string	必填。 工作流运行状态变化。
workflow	object	必填。 工作流定义。
workflow_run	object	必填。 被操作的工作流运行记录。
pull_request	object	当该工作流运行与某个 pull request 相关时会出现。
organization	object	当仓库所有者是组织时会出现。
repository	object	必填。 包含该工作流的仓库。
sender	object	必填。 触发该工作流运行更新的用户。

workflow_job

当 Gitea Actions 工作流任务状态发生变化时，会触发此事件。

动作类型： queued、waiting、in_progress、completed

Payload 参数

名称	类型	说明
action	string	必填。 工作流任务状态变化。
workflow_job	object	必填。 被操作的工作流任务。
pull_request	object	当该工作流任务与某个 pull request 相关时会出现。
organization	object	当仓库所有者是组织时会出现。
repository	object	必填。 包含该工作流任务的仓库。
sender	object	必填。 触发该工作流任务更新的用户。

测试、最近投递与重放

每个 Webhook 页面都包含：

• Test Delivery：会向仓库发送一次模拟的 push 事件。
• Recent Deliveries：显示请求和响应详情。
• Redelivery：重新投递一次历史 Webhook 记录。

如果仓库还没有任何提交，测试投递会使用一个生成的假提交，以便仍然可以测试 Webhook。

管理说明

管理员还可以通过实例级设置控制 Webhook 投递，例如主机允许列表、投递超时和 清理策略。详见 配置速查表中的 Webhook 小节。