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