gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-07-21 18:27:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

update webhook documentation (#393)

Browse Source 
Reviewed-on: https://gitea.com/gitea/docs/pulls/393
This commit is contained in:
Lunny Xiao
2026-05-01 16:40:27 +00:00
parent f550d33ad7
commit 14b76120b4
9 changed files with 6063 additions and 1227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

807
i18n/zh-tw/docusaurus-plugin-content-docs/current/usage/repository/webhooks.md
View File

@@ -8,178 +8,713 @@ aliases:
# Webhooks
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
所有事件推送都是 POST 请求。目前支持：
Gitea 可以為儲存庫活動送出對外 Webhook。儲存庫層級的 Webhook 由儲存庫管理員
在 `/:username/:reponame/settings/hooks` 中設定。組織、使用者與系統管理層級
也有對應的 Webhook 設定頁面。
- Gitea (也可以是 GET 请求)
Webhook 設定支援四種範圍：
- `儲存庫 Webhook`：只會對單一儲存庫中的活動觸發。
- `組織 Webhook`：對該組織擁有的儲存庫中的活動觸發。
- `使用者 Webhook`：對該使用者擁有的儲存庫中的活動觸發。
- `系統 Webhook`：對實例中所有符合條件的活動觸發。
Gitea 也支援由管理員定義的 `預設 Webhook`。它並不是額外的投遞範圍，而是會在
建立新儲存庫時被複製到該儲存庫中，之後就會像一般儲存庫 Webhook 一樣運作。
Gitea 支援以下對外 Webhook 整合：
- Gitea
- Gogs
- Slack
- Discord
- Dingtalk（钉钉）
- Dingtalk
- Telegram
- Microsoft Teams
- Feishu
- Wechatwork（企业微信）
- Matrix
- Wechatwork
- Packagist
### 事件信息
`Gitea` 與 `Gogs` 類型會送出通用 Webhook payload。上面列出的聊天與服務整合
則會把同一個內部事件轉換成各自服務所需的請求主體格式。
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
本頁分成三個部分：
以下是 Gitea 将发送给 payload URL 的事件信息示例：
- `設定`：如何設定 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`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
相容的 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
它與 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 事件群組：
```http
X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-GitHub-Event: push
X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gogs-Event: push
X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gitea-Event: push
X-Gitea-Event: issues
X-Gitea-Event-Type: issue_assign
X-GitHub-Event: issues
X-GitHub-Event-Type: issue_assign
```
```json
{
"secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
"ref": "refs/heads/develop",
"before": "28e1879d029cb852e4844d9c718537df08844e03",
"after": "bffeb74224043ba2feb48d137756c8a9331c449a",
"compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
"commits": [
{
"id": "bffeb74224043ba2feb48d137756c8a9331c449a",
"message": "Webhooks Yay!",
"url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
"author": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"committer": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"timestamp": "2017-03-13T13:52:11-04:00"
}
],
"repository": {
"id": 140,
"owner": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"name": "webhooks",
"full_name": "gitea/webhooks",
"description": "",
"private": false,
"fork": false,
"html_url": "http://localhost:3000/gitea/webhooks",
"ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
"clone_url": "http://localhost:3000/gitea/webhooks.git",
"website": "",
"stars_count": 0,
"forks_count": 1,
"watchers_count": 1,
"open_issues_count": 7,
"default_branch": "master",
"created_at": "2017-02-26T04:29:06-05:00",
"updated_at": "2017-03-13T13:51:58-04:00"
},
"pusher": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"sender": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
}
}
```
如果你需要知道實際觸發投遞的具體事件類型，請使用 `X-Gitea-Event-Type`。
### 示例
#### 驗證投遞
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
Gitea 會使用你的 Webhook 密鑰對原始請求主體進行簽章。要驗證一次投遞：
- 目标 URL：http://mydomain.com/webhook.php
- HTTP 方法：POST
- POST Content Type：application/json
- Secret：123
- 触发条件：推送事件
- 激活：勾选
1. 以接收到的原始內容讀取請求主體。
2. 使用 Webhook 密鑰計算 HMAC-SHA256 摘要。
3. 將結果與 `X-Gitea-Signature` 或 GitHub 相容的
`X-Hub-Signature-256` 進行比較。
4. 盡量使用常數時間比較函式。
现在在你的服务器上创建 php 文件 webhook.php。
注意事項：
- `X-Gitea-Signature` 只包含小寫十六進位的 SHA-256 摘要。
- `X-Hub-Signature-256` 使用相同摘要，但帶有 `sha256=` 前綴。
- `X-Hub-Signature` 也會為了相容性而送出，其演算法為 SHA-1。
- 在完成簽章驗證之前，不應先解析 JSON 或修改請求主體。
##### PHP 範例
下面的範例示範如何驗證以 `application/json` 送出的通用 `Gitea` Webhook。
```php
<?php
$secret_key = '123';
$secret = '123';
// check for POST request
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
exit();
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
exit('Only POST is allowed');
}
// get content type
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
if ($content_type != 'application/json') {
error_log('FAILED - not application/json - '. $content_type);
exit();
if ($payload === false || $signature === '') {
http_response_code(400);
exit('Missing payload or signature');
}
// get payload
$payload = trim(file_get_contents("php://input"));
$expected = hash_hmac('sha256', $payload, $secret);
if (empty($payload)) {
error_log('FAILED - no payload');
exit();
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
// get header signature
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
$data = json_decode($payload, true);
if (empty($header_signature)) {
error_log('FAILED - header signature missing');
exit();
if (!is_array($data)) {
http_response_code(400);
exit('Invalid JSON payload');
}
// calculate payload signature
$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
// check payload signature against header signature
if ($header_signature !== $payload_signature) {
error_log('FAILED - payload signature');
exit();
}
// convert json to array
$decoded = json_decode($payload, true);
// check for json decode errors
if (json_last_error() !== JSON_ERROR_NONE) {
error_log('FAILED - json decode - '. json_last_error());
exit();
}
// success, do something
http_response_code(204);
```
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
## 事件
### 授权头（Authorization header）
本節採用與 GitHub Webhook 文件類似的逐事件描述方式：每個事件都會說明
觸發時機，以及 payload 中包含哪些頂層欄位。
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
事件分組與 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` | **必填。** 審查 payload。對此事件而言，`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` | **必填。** 審查 payload。對此事件而言，`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` | **必填。** 審查 payload。對此事件而言，`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 小節](../../administration/config-cheat-sheet.md#webhook-webhook)。

807
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.25/usage/repository/webhooks.md
View File

@@ -8,178 +8,713 @@ aliases:
# Webhooks
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
所有事件推送都是 POST 请求。目前支持：
Gitea 可以為儲存庫活動送出對外 Webhook。儲存庫層級的 Webhook 由儲存庫管理員
在 `/:username/:reponame/settings/hooks` 中設定。組織、使用者與系統管理層級
也有對應的 Webhook 設定頁面。
- Gitea (也可以是 GET 请求)
Webhook 設定支援四種範圍：
- `儲存庫 Webhook`：只會對單一儲存庫中的活動觸發。
- `組織 Webhook`：對該組織擁有的儲存庫中的活動觸發。
- `使用者 Webhook`：對該使用者擁有的儲存庫中的活動觸發。
- `系統 Webhook`：對實例中所有符合條件的活動觸發。
Gitea 也支援由管理員定義的 `預設 Webhook`。它並不是額外的投遞範圍，而是會在
建立新儲存庫時被複製到該儲存庫中，之後就會像一般儲存庫 Webhook 一樣運作。
Gitea 支援以下對外 Webhook 整合：
- Gitea
- Gogs
- Slack
- Discord
- Dingtalk（钉钉）
- Dingtalk
- Telegram
- Microsoft Teams
- Feishu
- Wechatwork（企业微信）
- Matrix
- Wechatwork
- Packagist
### 事件信息
`Gitea` 與 `Gogs` 類型會送出通用 Webhook payload。上面列出的聊天與服務整合
則會把同一個內部事件轉換成各自服務所需的請求主體格式。
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
本頁分成三個部分：
以下是 Gitea 将发送给 payload URL 的事件信息示例：
- `設定`：如何設定 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`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
相容的 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
它與 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 事件群組：
```http
X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-GitHub-Event: push
X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gogs-Event: push
X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gitea-Event: push
X-Gitea-Event: issues
X-Gitea-Event-Type: issue_assign
X-GitHub-Event: issues
X-GitHub-Event-Type: issue_assign
```
```json
{
"secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
"ref": "refs/heads/develop",
"before": "28e1879d029cb852e4844d9c718537df08844e03",
"after": "bffeb74224043ba2feb48d137756c8a9331c449a",
"compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
"commits": [
{
"id": "bffeb74224043ba2feb48d137756c8a9331c449a",
"message": "Webhooks Yay!",
"url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
"author": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"committer": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"timestamp": "2017-03-13T13:52:11-04:00"
}
],
"repository": {
"id": 140,
"owner": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"name": "webhooks",
"full_name": "gitea/webhooks",
"description": "",
"private": false,
"fork": false,
"html_url": "http://localhost:3000/gitea/webhooks",
"ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
"clone_url": "http://localhost:3000/gitea/webhooks.git",
"website": "",
"stars_count": 0,
"forks_count": 1,
"watchers_count": 1,
"open_issues_count": 7,
"default_branch": "master",
"created_at": "2017-02-26T04:29:06-05:00",
"updated_at": "2017-03-13T13:51:58-04:00"
},
"pusher": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"sender": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
}
}
```
如果你需要知道實際觸發投遞的具體事件類型，請使用 `X-Gitea-Event-Type`。
### 示例
#### 驗證投遞
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
Gitea 會使用你的 Webhook 密鑰對原始請求主體進行簽章。要驗證一次投遞：
- 目标 URL：http://mydomain.com/webhook.php
- HTTP 方法：POST
- POST Content Type：application/json
- Secret：123
- 触发条件：推送事件
- 激活：勾选
1. 以接收到的原始內容讀取請求主體。
2. 使用 Webhook 密鑰計算 HMAC-SHA256 摘要。
3. 將結果與 `X-Gitea-Signature` 或 GitHub 相容的
`X-Hub-Signature-256` 進行比較。
4. 盡量使用常數時間比較函式。
现在在你的服务器上创建 php 文件 webhook.php。
注意事項：
- `X-Gitea-Signature` 只包含小寫十六進位的 SHA-256 摘要。
- `X-Hub-Signature-256` 使用相同摘要，但帶有 `sha256=` 前綴。
- `X-Hub-Signature` 也會為了相容性而送出，其演算法為 SHA-1。
- 在完成簽章驗證之前，不應先解析 JSON 或修改請求主體。
##### PHP 範例
下面的範例示範如何驗證以 `application/json` 送出的通用 `Gitea` Webhook。
```php
<?php
$secret_key = '123';
$secret = '123';
// check for POST request
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
exit();
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
exit('Only POST is allowed');
}
// get content type
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
if ($content_type != 'application/json') {
error_log('FAILED - not application/json - '. $content_type);
exit();
if ($payload === false || $signature === '') {
http_response_code(400);
exit('Missing payload or signature');
}
// get payload
$payload = trim(file_get_contents("php://input"));
$expected = hash_hmac('sha256', $payload, $secret);
if (empty($payload)) {
error_log('FAILED - no payload');
exit();
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
// get header signature
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
$data = json_decode($payload, true);
if (empty($header_signature)) {
error_log('FAILED - header signature missing');
exit();
if (!is_array($data)) {
http_response_code(400);
exit('Invalid JSON payload');
}
// calculate payload signature
$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
// check payload signature against header signature
if ($header_signature !== $payload_signature) {
error_log('FAILED - payload signature');
exit();
}
// convert json to array
$decoded = json_decode($payload, true);
// check for json decode errors
if (json_last_error() !== JSON_ERROR_NONE) {
error_log('FAILED - json decode - '. json_last_error());
exit();
}
// success, do something
http_response_code(204);
```
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
## 事件
### 授权头（Authorization header）
本節採用與 GitHub Webhook 文件類似的逐事件描述方式：每個事件都會說明
觸發時機，以及 payload 中包含哪些頂層欄位。
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
事件分組與 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` | **必填。** 審查 payload。對此事件而言，`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` | **必填。** 審查 payload。對此事件而言，`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` | **必填。** 審查 payload。對此事件而言，`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 小節](../../administration/config-cheat-sheet.md#webhook-webhook)。

807
i18n/zh-tw/docusaurus-plugin-content-docs/version-1.26/usage/repository/webhooks.md
View File

@@ -8,178 +8,713 @@ aliases:
# Webhooks
Gitea 支持用于仓库事件的 Webhooks。这可以在仓库管理员在设置页面 `/:username/:reponame/settings/hooks` 中进行配置。Webhooks 还可以基于组织和整个系统进行配置。
所有事件推送都是 POST 请求。目前支持：
Gitea 可以為儲存庫活動送出對外 Webhook。儲存庫層級的 Webhook 由儲存庫管理員
在 `/:username/:reponame/settings/hooks` 中設定。組織、使用者與系統管理層級
也有對應的 Webhook 設定頁面。
- Gitea (也可以是 GET 请求)
Webhook 設定支援四種範圍：
- `儲存庫 Webhook`：只會對單一儲存庫中的活動觸發。
- `組織 Webhook`：對該組織擁有的儲存庫中的活動觸發。
- `使用者 Webhook`：對該使用者擁有的儲存庫中的活動觸發。
- `系統 Webhook`：對實例中所有符合條件的活動觸發。
Gitea 也支援由管理員定義的 `預設 Webhook`。它並不是額外的投遞範圍，而是會在
建立新儲存庫時被複製到該儲存庫中，之後就會像一般儲存庫 Webhook 一樣運作。
Gitea 支援以下對外 Webhook 整合：
- Gitea
- Gogs
- Slack
- Discord
- Dingtalk（钉钉）
- Dingtalk
- Telegram
- Microsoft Teams
- Feishu
- Wechatwork（企业微信）
- Matrix
- Wechatwork
- Packagist
### 事件信息
`Gitea` 與 `Gogs` 類型會送出通用 Webhook payload。上面列出的聊天與服務整合
則會把同一個內部事件轉換成各自服務所需的請求主體格式。
**警告**：自 Gitea 1.13.0 版起，payload 中的 `secret` 字段已被弃用，并将在 1.14.0 版中移除：https://github.com/go-gitea/gitea/issues/11755
本頁分成三個部分：
以下是 Gitea 将发送给 payload URL 的事件信息示例：
- `設定`：如何設定 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`](https://pkg.go.dev/github.com/gobwas/glob#Compile)
相容的 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
它與 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 事件群組：
```http
X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-GitHub-Event: push
X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gogs-Event: push
X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gitea-Event: push
X-Gitea-Event: issues
X-Gitea-Event-Type: issue_assign
X-GitHub-Event: issues
X-GitHub-Event-Type: issue_assign
```
```json
{
"secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
"ref": "refs/heads/develop",
"before": "28e1879d029cb852e4844d9c718537df08844e03",
"after": "bffeb74224043ba2feb48d137756c8a9331c449a",
"compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
"commits": [
{
"id": "bffeb74224043ba2feb48d137756c8a9331c449a",
"message": "Webhooks Yay!",
"url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
"author": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"committer": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"timestamp": "2017-03-13T13:52:11-04:00"
}
],
"repository": {
"id": 140,
"owner": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"name": "webhooks",
"full_name": "gitea/webhooks",
"description": "",
"private": false,
"fork": false,
"html_url": "http://localhost:3000/gitea/webhooks",
"ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
"clone_url": "http://localhost:3000/gitea/webhooks.git",
"website": "",
"stars_count": 0,
"forks_count": 1,
"watchers_count": 1,
"open_issues_count": 7,
"default_branch": "master",
"created_at": "2017-02-26T04:29:06-05:00",
"updated_at": "2017-03-13T13:51:58-04:00"
},
"pusher": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"sender": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
}
}
```
如果你需要知道實際觸發投遞的具體事件類型，請使用 `X-Gitea-Event-Type`。
### 示例
#### 驗證投遞
这是一个示例，演示如何使用 Webhooks 在推送请求到达仓库时运行一个 php 脚本。
在你的仓库设置中，在 Webhooks 下，设置一个如下的 Gitea webhook：
Gitea 會使用你的 Webhook 密鑰對原始請求主體進行簽章。要驗證一次投遞：
- 目标 URL：http://mydomain.com/webhook.php
- HTTP 方法：POST
- POST Content Type：application/json
- Secret：123
- 触发条件：推送事件
- 激活：勾选
1. 以接收到的原始內容讀取請求主體。
2. 使用 Webhook 密鑰計算 HMAC-SHA256 摘要。
3. 將結果與 `X-Gitea-Signature` 或 GitHub 相容的
`X-Hub-Signature-256` 進行比較。
4. 盡量使用常數時間比較函式。
现在在你的服务器上创建 php 文件 webhook.php。
注意事項：
- `X-Gitea-Signature` 只包含小寫十六進位的 SHA-256 摘要。
- `X-Hub-Signature-256` 使用相同摘要，但帶有 `sha256=` 前綴。
- `X-Hub-Signature` 也會為了相容性而送出，其演算法為 SHA-1。
- 在完成簽章驗證之前，不應先解析 JSON 或修改請求主體。
##### PHP 範例
下面的範例示範如何驗證以 `application/json` 送出的通用 `Gitea` Webhook。
```php
<?php
$secret_key = '123';
$secret = '123';
// check for POST request
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
exit();
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
exit('Only POST is allowed');
}
// get content type
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
if ($content_type != 'application/json') {
error_log('FAILED - not application/json - '. $content_type);
exit();
if ($payload === false || $signature === '') {
http_response_code(400);
exit('Missing payload or signature');
}
// get payload
$payload = trim(file_get_contents("php://input"));
$expected = hash_hmac('sha256', $payload, $secret);
if (empty($payload)) {
error_log('FAILED - no payload');
exit();
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
// get header signature
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
$data = json_decode($payload, true);
if (empty($header_signature)) {
error_log('FAILED - header signature missing');
exit();
if (!is_array($data)) {
http_response_code(400);
exit('Invalid JSON payload');
}
// calculate payload signature
$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
// check payload signature against header signature
if ($header_signature !== $payload_signature) {
error_log('FAILED - payload signature');
exit();
}
// convert json to array
$decoded = json_decode($payload, true);
// check for json decode errors
if (json_last_error() !== JSON_ERROR_NONE) {
error_log('FAILED - json decode - '. json_last_error());
exit();
}
// success, do something
http_response_code(204);
```
在 Webhook 设置中有一个“测试推送（Test Delivery）”按钮，可以测试配置，还有一个“最近推送记录（Recent Deliveries）”的列表。
## 事件
### 授权头（Authorization header）
本節採用與 GitHub Webhook 文件類似的逐事件描述方式：每個事件都會說明
觸發時機，以及 payload 中包含哪些頂層欄位。
**从 1.19 版本开始**，Gitea 的 Webhook 可以配置为向 Webhook 目标发送一个 [授权头（authorization header）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)。
事件分組與 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` | **必填。** 審查 payload。對此事件而言，`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` | **必填。** 審查 payload。對此事件而言，`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` | **必填。** 審查 payload。對此事件而言，`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 小節](../../administration/config-cheat-sheet.md#webhook-webhook)。