mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-07 10:30:32 +00:00
Add version v28 (#564)
<!-- cloudflare-preview --> Preview: https://pr-564.docs-gitea-com.pages.dev Reviewed-on: https://gitea.com/gitea/docs/pulls/564 Reviewed-by: bircni <[email protected]> Co-authored-by: Lunny Xiao <[email protected]>
This commit is contained in:
Lunny Xiao authored and 
bircni committed
1 parent
deb2f068d4
commit
ba60edbbda
338 files changed
+114457
-47
No files matched your search
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"label": "Repository",
|
||||
"position": 10,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"slug": "/usage/repository",
|
||||
"description": "Repository management, Git operations, and content features"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
|
||||
slug: "clone-filters"
|
||||
sidebar_position: 25
|
||||
aliases:
|
||||
- /zh-tw/clone-filters
|
||||
---
|
||||
|
||||
# 克隆過濾器 (部分克隆)
|
||||
|
||||
Git 引入了 `--filter` 選項用於 `git clone` 命令，該選項可以過濾掉大文件和對象（如 blob），從而建立一個儲存庫的部分克隆。克隆過濾器對於大型儲存庫和/或按流量計費的連接特別有用，因為完全克隆（不使用 `--filter`）可能會很昂貴（需要下載所有歷史資料）。
|
||||
|
||||
這需要 Git 2.22 或更高版本，無論是在 Gitea 伺服器上還是在客戶端上都需要如此。為了使克隆過濾器正常工作，請確保客戶端上的 Git 版本至少與伺服器上的版本相同（或更高）。以管理員身份登入到 Gitea，然後轉到管理後臺 -> 應用設定，查看伺服器的 Git 版本。
|
||||
|
||||
預設情況下，克隆過濾器是啟用的，除非在 `[git]` 下將 `DISABLE_PARTIAL_CLONE` 設定為 `true`。
|
||||
|
||||
請參閱 [GitHub 部落格文章：瞭解部分克隆](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/) 以獲取克隆過濾器的常見用法（無 Blob 和無樹的克隆），以及 [GitLab 部分克隆文件](https://docs.gitlab.com/ee/topics/git/partial_clone.html) 以獲取更高級的用法（例如按文件大小過濾和取消過濾以將部分克隆轉換為完全克隆）。
|
||||
+38
@@ -0,0 +1,38 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
|
||||
slug: "incoming-email"
|
||||
sidebar_position: 13
|
||||
aliases:
|
||||
- /zh-tw/incoming-email
|
||||
---
|
||||
|
||||
# 郵件接收
|
||||
|
||||
Gitea 支援通過接收郵件執行多種操作。本頁面描述瞭如何進行設定。
|
||||
|
||||
## 要求
|
||||
|
||||
處理接收的電子郵件需要啟用 IMAP 功能的電子郵件帳戶。
|
||||
推薦的策略是使用 [電子郵件子地址](https://en.wikipedia.org/wiki/Email_address#Sub-addressing)，但也可以使用 catch-all 郵箱。
|
||||
接收電子電子郵件地址中包含一個使用者/操作特定的令牌，告訴 Gitea 應執行哪個操作。
|
||||
此令牌應該出現在 `To` 和 `Delivered-To` 頭欄位中。
|
||||
|
||||
Gitea 會嘗試檢測自動回覆並跳過它們，電子郵件伺服器也應該設定以減少接收到的干擾（垃圾郵件、通訊訂閱等）。
|
||||
|
||||
## 設定
|
||||
|
||||
要激活處理接收的電子郵件消息功能，您需要在設定文件中設定 `email.incoming` 部分。
|
||||
|
||||
`REPLY_TO_ADDRESS` 包含電子郵件客戶端將要回復的地址。
|
||||
該地址需要包含 `%{token}` 佔位符，該佔位符將被替換為描述使用者/操作的令牌。
|
||||
此佔位符在地址中只能出現一次，並且必須位於地址的使用者部分（`@` 之前）。
|
||||
|
||||
使用電子郵件子地址的範例可能如下：`incoming+%{token}@example.com`
|
||||
|
||||
如果使用 catch-all 郵箱，則佔位符可以出現在地址的使用者部分的任何位置：`incoming+%{token}@example.com`、`incoming_%{token}@example.com`、`%{token}@example.com`
|
||||
|
||||
## 安全性
|
||||
|
||||
在選擇用於接收傳入電子郵件的域時要小心。
|
||||
建議在子域名上接收傳入電子郵件，例如 `incoming.example.com`，以防止與運行在 `example.com` 上的其他服務可能存在的安全問題。
|
||||
+15
@@ -0,0 +1,15 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "profile-readme"
|
||||
sidebar_position: 12
|
||||
---
|
||||
|
||||
# 個人資料 README
|
||||
|
||||
要在您的 Gitea 個人資料頁面顯示一個 Markdown 文件，只需建立一個名為 `.profile` 的儲存庫，並編輯其中的 `README.md` 文件。Gitea 將自動獲取該文件並在您的儲存庫上方顯示。
|
||||
|
||||
注意：您可以將此儲存庫設為私有。這樣可以隱藏您的源文件，使其對公眾不可見，並允許您將某些文件設為私有。但是，README.md 文件將是您個人資料上唯一存在的文件。如果您希望完全私有化 .profile 儲存庫，則需刪除或重命名 README.md 文件。
|
||||
|
||||
使用者範例 `.profile/README.md`:
|
||||
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "push"
|
||||
sidebar_position: 15
|
||||
aliases:
|
||||
- /zh-tw/push-to-create
|
||||
- /zh-tw/push-options
|
||||
---
|
||||
|
||||
# 推送
|
||||
|
||||
在將提交推送到 Gitea 伺服器時，還有一些額外的功能。
|
||||
|
||||
## 通過推送打開 PR
|
||||
|
||||
當您第一次將提交推送到非預設分支時，您將收到一個鏈接，您可以單擊該鏈接訪問分支與主分支的比較頁面。
|
||||
從那裡，您可以輕鬆建立一個拉取請求，即使您想要將其目標指向另一個分支。
|
||||
|
||||
|
||||
|
||||
## 推送選項
|
||||
|
||||
在 Gitea `1.13` 版本中，添加了對一些 [推送選項](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) 的支援。
|
||||
|
||||
### 支援的選項
|
||||
|
||||
- `repo.private` (true|false) - 更改儲存庫的可見性。
|
||||
|
||||
這在與 push-to-create 結合使用時特別有用。
|
||||
|
||||
- `repo.template` (true|false) - 更改儲存庫是否為模板。
|
||||
|
||||
將儲存庫的可見性更改為公開的範例：
|
||||
|
||||
```shell
|
||||
git push -o repo.private=false -u origin main
|
||||
```
|
||||
|
||||
## 推送建立
|
||||
|
||||
推送建立是一項功能，允許您將提交推送到在 Gitea 中尚不存在的儲存庫。這對於自動化和允許使用者建立儲存庫而無需通過 Web 介面非常有用。此功能預設處於禁用狀態。
|
||||
|
||||
### 啟用推送建立
|
||||
|
||||
在 `app.ini` 文件中，將 `ENABLE_PUSH_CREATE_USER` 設定為 `true`，如果您希望允許使用者在自己的使用者帳戶和所屬的組織中建立儲存庫，將 `ENABLE_PUSH_CREATE_ORG` 設定為 `true`。重新啟動 Gitea 以使更改生效。您可以在 [設定速查表](../../administration/config-cheat-sheet.md#儲存庫-repository) 中瞭解有關這兩個選項的更多資訊。
|
||||
|
||||
### 使用推送建立
|
||||
|
||||
假設您在當前目錄中有一個 git 儲存庫，您可以透過運行以下命令將提交推送到在 Gitea 中尚不存在的儲存庫：
|
||||
|
||||
```shell
|
||||
# 添加要推送到的遠程倉庫
|
||||
git remote add origin git@{domain}:{username}/{尚不存在的倉庫名稱}.git
|
||||
|
||||
# 推送到遠程倉庫
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
這假設您使用的是 SSH 遠程，但您也可以使用 HTTPS 遠程。
|
||||
|
||||
推送建立將預設使用 `app.ini` 中定義的可見性 `DEFAULT_PUSH_CREATE_PRIVATE`。
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "repo-mirror"
|
||||
sidebar_position: 45
|
||||
aliases:
|
||||
- /zh-tw/repo-mirror
|
||||
---
|
||||
|
||||
# 儲存庫鏡像
|
||||
|
||||
儲存庫鏡像允許將儲存庫與外部源之間進行鏡像。您可以使用它在儲存庫之間鏡像分支、標籤和提交。
|
||||
|
||||
## 使用場景
|
||||
|
||||
以下是一些儲存庫鏡像的可能使用場景：
|
||||
|
||||
- 您遷移到了 Gitea，但仍需要在其他源中保留您的專案。在這種情況下，您可以簡單地設定它以進行鏡像到 Gitea（拉取），這樣您的 Gitea 實例中就可以獲取到所有必要的提交歷史、標籤和分支。
|
||||
- 您在其他源中有一些舊專案，您不再主動使用，但出於歸檔目的不想刪除。在這種情況下，您可以建立一個推送鏡像，以便您的活躍的 Gitea 儲存庫可以將其更改推送到舊位置。
|
||||
|
||||
## 從遠程儲存庫拉取
|
||||
|
||||
對於現有的遠程儲存庫，您可以按照以下步驟設定拉取鏡像：
|
||||
|
||||
1. 在右上角的“建立...”菜單中選擇“遷移外部儲存庫”。
|
||||
2. 選擇遠程儲存庫服務。
|
||||
3. 輸入儲存庫的 URL。
|
||||
4. 如果儲存庫需要身份驗證，請填寫您的身份驗證資訊。
|
||||
5. 選中“該儲存庫將是一個鏡像”複選框。
|
||||
6. 選擇“遷移儲存庫”以保存設定。
|
||||
|
||||
現在，該儲存庫會定期從遠程儲存庫進行鏡像。您可以透過在儲存庫設定中選擇“立即同步”來強制進行同步。
|
||||
|
||||
:::warning
|
||||
:exclamation::exclamation: **注意：**您只能為尚不存在於您的實例上的儲存庫設定拉取鏡像。一旦儲存庫建立成功，您就無法再將其轉換為拉取鏡像。:exclamation::exclamation:
|
||||
:::
|
||||
|
||||
## 推送到遠程儲存庫
|
||||
|
||||
對於現有的儲存庫，您可以按照以下步驟設定推送鏡像：
|
||||
|
||||
1. 在儲存庫中，轉到**設定** > **儲存庫**，然後進入**鏡像設定**部分。
|
||||
2. 輸入一個儲存庫的 URL。
|
||||
3. 如果儲存庫需要身份驗證，請展開**授權**部分並填寫您的身份驗證資訊。請注意，所請求的**密碼**也可以是您的存取權杖。
|
||||
4. 選擇**添加推送鏡像**以保存設定。
|
||||
|
||||
該儲存庫現在會定期鏡像到遠程儲存庫。您可以透過選擇**立即同步**來強制同步。如果出現錯誤，會顯示一條消息幫助您解決問題。
|
||||
|
||||
:::warning
|
||||
:exclamation::exclamation: **注意：** 這將強制推送到遠程儲存庫。這將覆蓋遠程儲存庫中的任何更改！ :exclamation::exclamation:
|
||||
:::
|
||||
|
||||
### 從 Gitea 向 GitHub 設定推送鏡像
|
||||
|
||||
要從 Gitea 設定鏡像到 GitHub，您需要按照以下步驟進行操作：
|
||||
|
||||
1. 建立一個具有選中 _public_repo_ 選項的 [GitHub 個人存取權杖](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token)。
|
||||
2. 在 GitHub 上建立一個同名的儲存庫。與 Gitea 不同，GitHub 不支援通過推送到遠程來建立儲存庫。如果您的現有遠程儲存庫與您的 Gitea 儲存庫具有相同的提交歷史，您也可以使用現有的遠程儲存庫。
|
||||
3. 在您的 Gitea 儲存庫設定中，填寫**Git 遠程儲存庫 URL**：`https://github.com/<your_github_group>/<your_github_project>.git`。
|
||||
4. 使用您的 GitHub 使用者名稱填寫**授權**欄位，並將個人存取權杖作為**密碼**。
|
||||
5. （可選，適用於 Gitea 1.18+）選擇`當推送新提交時同步`，這樣一旦有更改，鏡像將會及時更新。如果您願意，您還可以禁用定期同步。
|
||||
6. 選擇**添加推送鏡像**以保存設定。
|
||||
|
||||
儲存庫會很快進行推送。要強制推送，請選擇**立即同步**按鈕。
|
||||
|
||||
### 從 Gitea 向 GitLab 設定推送鏡像
|
||||
|
||||
要從 Gitea 設定鏡像到 GitLab，您需要按照以下步驟進行操作：
|
||||
|
||||
1. 建立具有 _write_repository_ 作用域的 [GitLab 個人存取權杖](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)。
|
||||
2. 填寫**Git 遠程儲存庫 URL**：`https://<destination host>/<your_gitlab_group_or_name>/<your_gitlab_project>.git`。
|
||||
3. 在**授權**欄位中填寫 `oauth2` 作為**使用者名稱**，並將您的 GitLab 個人存取權杖作為**密碼**。
|
||||
4. 選擇**添加推送鏡像**以保存設定。
|
||||
|
||||
儲存庫會很快進行推送。要強制推送，請選擇**立即同步**按鈕。
|
||||
|
||||
### 從 Gitea 向 Bitbucket 設定推送鏡像
|
||||
|
||||
要從 Gitea 設定鏡像到 Bitbucket，您需要按照以下步驟進行操作：
|
||||
|
||||
1. 建立一個具有選中 _Repository Write_ 選項的 [Bitbucket 應用密碼](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/)。
|
||||
2. 填寫**Git 遠程儲存庫 URL**：`https://bitbucket.org/<your_bitbucket_group_or_name>/<your_bitbucket_project>.git`。
|
||||
3. 使用您的 Bitbucket 使用者名稱填寫**授權**欄位，並將應用密碼作為**密碼**。
|
||||
4. 選擇**添加推送鏡像**以保存設定。
|
||||
|
||||
儲存庫會很快進行推送。要強制推送，請選擇**立即同步**按鈕。
|
||||
|
||||
### 鏡像現有的 ssh 儲存庫
|
||||
|
||||
當前，Gitea 不支援從 ssh 儲存庫進行鏡像。如果您想要鏡像一個 ssh 儲存庫，您需要將其轉換為 http 儲存庫。您可以使用以下命令將現有的 ssh 儲存庫轉換為 http 儲存庫：
|
||||
|
||||
1. 確保運行 gitea 的使用者有權限訪問您試圖從 shell 鏡像到的 git 儲存庫。
|
||||
2. 在 Web 介面的版本庫設定 > git 鉤子中為鏡像添加一個接收後鉤子。
|
||||
|
||||
```
|
||||
#!/usr/bin/env bash
|
||||
git push --mirror --quiet [email protected]:username/repository.git &>/dev/null &
|
||||
echo "GitHub mirror initiated .."
|
||||
```
|
||||
+76
@@ -0,0 +1,76 @@
|
||||
---
|
||||
date: "2023-05-23T09:00:00+08:00"
|
||||
slug: "template-repositories"
|
||||
sidebar_position: 14
|
||||
aliases:
|
||||
- /zh-tw/template-repositories
|
||||
---
|
||||
|
||||
# 模板儲存庫
|
||||
|
||||
Gitea `1.11.0` 及以上版本引入了模板儲存庫，並且其中一個實現的功能是自動展開模板文件中的特定變量。
|
||||
|
||||
要告訴 Gitea 哪些文件需要展開，您必須在模板儲存庫的 `.gitea` 目錄中包含一個 `template` 文件。
|
||||
|
||||
Gitea 使用 [gobwas/glob](https://github.com/gobwas/glob) 作為其 glob 語法。它與傳統的 `.gitignore` 語法非常相似，但可能存在細微的差異。
|
||||
|
||||
## `.gitea/template` 文件範例
|
||||
|
||||
所有路徑都是相對於儲存庫的根目錄
|
||||
|
||||
```gitignore
|
||||
# 倉庫中的所有 .go 文件
|
||||
**.go
|
||||
|
||||
# text 目錄中的所有文本文件
|
||||
text/*.txt
|
||||
|
||||
# 特定文件
|
||||
a/b/c/d.json
|
||||
|
||||
# 匹配批處理文件的大小寫變體
|
||||
**.[bB][aA][tT]
|
||||
```
|
||||
|
||||
**注意：** 當從模板生成儲存庫時，`.gitea` 目錄中的 `template` 文件將被刪除。
|
||||
|
||||
## 參數展開
|
||||
|
||||
在與上述通配符匹配的任何文件中，將會擴展某些變量。
|
||||
|
||||
文件名和路徑的匹配也可以被擴展，並且會經過謹慎的清理處理，以支援跨平台的文件系統。
|
||||
|
||||
所有變量都必須採用`$VAR`或`${VAR}`的形式。要轉義擴展，使用雙重`$$`，例如`$$VAR`或`$${VAR}`。
|
||||
|
||||
| 變量 | 擴展為 | 可轉換 |
|
||||
| -------------------- | ----------------------------- | ------ |
|
||||
| REPO_NAME | 生成的儲存庫名稱 | ✓ |
|
||||
| TEMPLATE_NAME | 模板儲存庫名稱 | ✓ |
|
||||
| REPO_DESCRIPTION | 生成的儲存庫描述 | ✘ |
|
||||
| TEMPLATE_DESCRIPTION | 模板儲存庫描述 | ✘ |
|
||||
| REPO_OWNER | 生成的儲存庫所有者 | ✓ |
|
||||
| TEMPLATE_OWNER | 模板儲存庫所有者 | ✓ |
|
||||
| REPO_LINK | 生成的儲存庫鏈接 | ✘ |
|
||||
| TEMPLATE_LINK | 模板儲存庫鏈接 | ✘ |
|
||||
| REPO_HTTPS_URL | 生成的儲存庫的 HTTP(S) 克隆鏈接 | ✘ |
|
||||
| TEMPLATE_HTTPS_URL | 模板儲存庫的 HTTP(S) 克隆鏈接 | ✘ |
|
||||
| REPO_SSH_URL | 生成的儲存庫的 SSH 克隆鏈接 | ✘ |
|
||||
| TEMPLATE_SSH_URL | 模板儲存庫的 SSH 克隆鏈接 | ✘ |
|
||||
|
||||
## 轉換器 :robot:
|
||||
|
||||
Gitea `1.12.0` 添加了一些轉換器以應用於上述適用的變量。
|
||||
|
||||
例如，要以 `PASCAL`-case 獲取 `REPO_NAME`，你的模板應使用 `${REPO_NAME_PASCAL}`
|
||||
|
||||
將 `go-sdk` 傳遞給可用的轉換器的效果如下...
|
||||
|
||||
| 轉換器 | 效果 |
|
||||
| ------ | ------ |
|
||||
| SNAKE | go_sdk |
|
||||
| KEBAB | go-sdk |
|
||||
| CAMEL | goSdk |
|
||||
| PASCAL | GoSdk |
|
||||
| LOWER | go-sdk |
|
||||
| UPPER | GO-SDK |
|
||||
| TITLE | Go-Sdk |
|
||||
@@ -0,0 +1,720 @@
|
||||
---
|
||||
date: "2016-12-01T16:00:00+02:00"
|
||||
slug: "webhooks"
|
||||
sidebar_position: 30
|
||||
aliases:
|
||||
- /zh-tw/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 payload。上面列出的聊天與服務整合
|
||||
則會把同一個內部事件轉換成各自服務所需的請求主體格式。
|
||||
|
||||
本頁分成三個部分：
|
||||
|
||||
- `設定`：如何設定 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-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
|
||||
<?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` | **必填。** 審查 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)。
|
||||
Reference in new issue
Block a user