Add version v28 (#564)

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]>
2026-11-09 11:30:30 +00:00 · 2026-09-30 06:40:44 +00:00
1 parent deb2f068d4
commit ba60edbbda
@@ -0,0 +1,126 @@
+---
+date: "2026-03-19T00:00:00+01:00"
+slug: "token-permissions"
+sidebar_position: 30
+---
+
+# Actions Job 令牌權限（`GITEA_TOKEN`）
+
+每個 Actions Job 都會取得一個內建令牌（`GITEA_TOKEN`），可用於存取 Gitea（透過 HTTP(S) 使用 Git、API 請求等）。
+本頁說明 Gitea 如何決定該令牌可以執行哪些操作。
+
+在工作流中，可以透過 `${{ secrets.GITEA_TOKEN }}` 使用它。這些設定和 `permissions:` 只影響 `GITEA_TOKEN`（不影響個人存取權杖等其他密鑰）。API 呼叫請參閱 [API 認證](../../development/api-usage.md#authentication)。
+
+<a id="where-permissions-come-from"></a>
+## 權限的來源
+
+Gitea 依以下順序決定 Job 令牌權限：
+
+1. Job 層級的 `permissions:`（`jobs.<job_id>.permissions`）
+2. 工作流層級的 `permissions:`（頂層）
+3. 設定中的預設權限（所有者或儲存庫）
+
+接著，結果會再受到所設定的最大令牌權限**限縮**（見下文）。
+
+<a id="supported-workflow-syntax"></a>
+## 支援的工作流語法
+
+Gitea 支援與 GitHub Actions 相容的 `permissions:` 關鍵字。
+
+<a id="scalar-values"></a>
+### 純量值
+
+```yaml
+permissions: read-all   # or: write-all
+```
+
+<a id="scoped-mapping"></a>
+### 依範圍對應
+
+```yaml
+permissions:
+  contents: read
+  issues: write
+  pull-requests: none
+```
+
+每個範圍的有效存取模式值為 `read`、`write` 和 `none`。
+
+<a id="supported-scopes"></a>
+### 支援的範圍
+
+- `contents`（適用於 `code` 和 `releases`）
+- `code`
+- `releases`
+- `issues`
+- `pull-requests`
+- `actions`
+- `wiki`
+- `projects`
+- `packages`（若目標功能支援）
+
+如果同時指定 `contents` 和更細的範圍（例如 `code` 或 `releases`），該單元以更細的範圍為準。
+
+<a id="compatibility-notes"></a>
+### 相容性說明
+
+Gitea 支援 GitHub Actions 權限範圍的一個子集。
+Gitea Actions 目前不支援 `statuses`、`checks`、`deployments`、`id-token`、`security-events` 和 `pages` 等 GitHub 專屬範圍。
+
+Gitea 另外提供一些儲存庫單元範圍，它們在 GitHub Actions 中並不是獨立的範圍：
+
+- `code`
+- `releases`
+- `wiki`
+- `projects`
+
+<a id="default-permission-mode"></a>
+## 預設權限模式
+
+如果工作流和 Job 都沒有定義 `permissions:`，Gitea 會使用所設定的預設模式：
+
+- **Permissive**（寬鬆）：對 Job 所屬儲存庫的大多數單元具有讀取和寫入權限（向下相容的預設值）。
+- **受限**（Restricted）：對 Job 所屬儲存庫的 `code`、`releases` 和 `packages` 具有唯讀權限，預設無法存取其他單元。
+
+<a id="maximum-token-permissions-clamping"></a>
+## 最大令牌權限（限縮）
+
+您可以為每個儲存庫單元設定最大權限。
+Job 的實際權限計算方式如下：
+
+`effective = min(requested, maximum)`
+
+也就是說，工作流可以降低 Job 的權限，但不能超過您所設定的最大值。
+如果未設定最大值，所有範圍的最大值預設為 `write`。
+
+<a id="where-to-configure"></a>
+## 設定位置
+
+您可以在以下位置設定預設值和最大值：
+
+- **使用者 / 組織**：`Settings` → `Actions` → `General`
+- **儲存庫**：`Settings` → `Actions` → `General`
+  - 對於組織內的儲存庫，儲存庫可以沿用所有者層級的設定，或透過 **Override owner-level configuration** 選擇退出。
+
+注意：只有在啟用**儲存庫 Actions** 後，才會顯示儲存庫層級的令牌權限設定。
+
+<a id="fork-pull-requests"></a>
+## 來自 fork 的拉取請求
+
+基於安全考量，由來自 fork 的拉取請求觸發的工作流，對儲存庫內容一律只有唯讀權限，不受工作流 `permissions:` 或設定影響。
+
+<a id="cross-repository-access"></a>
+## 跨儲存庫存取
+
+預設情況下，`GITEA_TOKEN` 只能存取：
+
+- Job 所屬的儲存庫（依計算出的權限）
+- 公開儲存庫（唯讀）
+
+預設會拒絕存取其他私有儲存庫。
+使用者或組織可以在**設定** > **Actions** > **General** > **Cross-Repository Access** 中，允許唯讀存取選定的私有儲存庫。
+
+私有儲存庫也可以在**設定** > **Actions** > **General** 中允許選定的協作所有者。
+這樣，這些所有者的私有儲存庫就能為了 Actions 用途讀取目前的私有儲存庫，例如私有 Actions 和可重複使用的工作流。
+
+由來自 fork 的拉取請求觸發的工作流，永遠無法取得對私有儲存庫的跨儲存庫存取權，即使這些儲存庫已列入清單也一樣。