mirror of
https://gitea.com/gitea/docs.git
synced 2026-11-07 18:40:32 +00:00
silverwind
c4caf767ad
Documents the `self:` and `builtin:` action prefixes from https://github.com/go-gitea/gitea/pull/39358, https://gitea.com/gitea/runner/pulls/1233 and https://gitea.com/gitea/runner/pulls/871, workflow-relative `$/` actions, and the runner's OpenTelemetry tracing from https://gitea.com/gitea/runner/pulls/1206. 1. Trims the action resolution and `DEFAULT_ACTIONS_URL` docs to state each fact once. 1. Drops outdated runner content from the FAQ and design pages. 1. Syncs zh-cn and zh-tw, including a port of the token permissions page they now link to. _Written by Claude._ Reviewed-on: https://gitea.com/gitea/docs/pulls/553 Reviewed-by: bircni <[email protected]> Co-authored-by: silverwind <[email protected]>
127 lines
4.4 KiB
Markdown
127 lines
4.4 KiB
Markdown
---
|
||
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 的拉取請求觸發的工作流，永遠無法取得對私有儲存庫的跨儲存庫存取權，即使這些儲存庫已列入清單也一樣。
|