docs(actions): document OIDC workload identity (#526)

Document the OpenID Connect tokens that Gitea Actions jobs can request since https://github.com/go-gitea/gitea/pull/39052, so they can sign in to cloud providers without long-lived secrets.

- Add an OpenID Connect page covering how to trust Gitea, request a token and match its claims
- Document the `id-token` permission scope and its maximum
- Translate both for zh-cn and zh-tw, which still listed `id-token` as unsupported

Co-authored-by: silverwind <[email protected]>
Co-authored-by: silverwind <[email protected]>
Reviewed-on: https://gitea.com/gitea/docs/pulls/526
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Max P. <[email protected]>

i18n/zh-cn/docs/current/usage/actions/comparison.md

@@ -88,7 +88,7 @@ Gitea Actions旨在与GitHub Actions兼容，差异如下。
 ### `permissions`和`jobs.<job_id>.permissions`
 
 `permissions`和`jobs.<job_id>.permissions`控制`GITEA_TOKEN`的权限，该权限受仓库和所有者设置的限制，并在fork拉取请求和跨仓库访问时受到进一步限制。
-不支持`statuses`、`checks`、`deployments`、`id-token`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。
+不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围，而Gitea额外提供了`code`、`releases`、`wiki`和`projects`。`id-token`与GitHub相同，请参阅[OpenID Connect](openid-connect.md)。
 请参阅[Actions Job令牌权限](token-permissions.md)。
 
 ### 下载Actions

i18n/zh-cn/docs/current/usage/actions/openid-connect.md

@@ -0,0 +1,63 @@
+---
+date: "2026-08-23T00:00:00+00:00"
+slug: "openid-connect"
+sidebar_position: 40
+---
+
+# OpenID Connect
+
+Job可以请求短期有效的OpenID Connect（OIDC）令牌来登录云服务商和其他服务，无需存储长期有效的密钥。这些令牌采用GitHub Actions的格式，因此`aws-actions/configure-aws-credentials`、`google-github-actions/auth`和`azure/login`等Action无需修改即可使用。
+
+<a id="trusting-gitea"></a>
+## 信任Gitea
+
+在服务中将Gitea添加为OIDC身份提供方：
+
+- Issuer：`<ROOT_URL>/api/actions/oidc`
+- Audience：`<ROOT_URL>/<owner>`，除非工作流请求了其他值
+
+然后通过[`sub`声明](#claims)上的条件限制哪些工作流可以登录。
+
+Gitea使用其在`<APP_DATA_PATH>/jwt/actions_oidc.pem`创建的密钥签名令牌。负载均衡器后的多个实例必须共享此文件。
+
+<a id="requesting-a-token"></a>
+## 请求令牌
+
+为工作流或Job授予`id-token`权限：
+
+```yaml
+permissions:
+  id-token: write
+```
+
+默认权限从不包含此权限，来自fork拉取请求的Job也永远无法获得。所有者和仓库可以通过[最大令牌权限](token-permissions.md#maximum-token-permissions-clamping)禁用它。
+
+上述Action会自行请求令牌。在脚本中，请使用`ACTIONS_ID_TOKEN_REQUEST_URL`和`ACTIONS_ID_TOKEN_REQUEST_TOKEN`：
+
+```shell
+curl --fail --silent --show-error \
+  --header "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
+  "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=my-service"
+```
+
+令牌位于响应的`value`字段中，五分钟后过期。
+
+<a id="claims"></a>
+## 声明
+
+`sub`声明包含所有者和仓库的名称及ID，因此重命名或重新创建的仓库无法匹配已有的信任策略：
+
+```text
+repo:<owner>@<owner-id>/<repo>@<repo-id>:ref:<ref>
+repo:<owner>@<owner-id>/<repo>@<repo-id>:pull_request
+```
+
+`pull_request`事件使用第二种格式，其他所有事件（包括`pull_request_target`）使用第一种。
+
+其他声明与GitHub相同，例如`repository`、`ref`、`sha`、`workflow_ref`和`job_workflow_ref`。位于`<ROOT_URL>/api/actions/oidc/.well-known/openid-configuration`的发现文档列出了所有声明。
+
+与GitHub Actions的区别：
+
+- 没有`environment`声明。
+- 拉取请求的运行使用`refs/pull/<index>/head`及其提交，而不是合并引用和合并提交。
+- `run_number`按仓库计数，而不是按工作流计数。

i18n/zh-cn/docs/current/usage/actions/token-permissions.md

@@ -58,6 +58,7 @@ permissions:
 - `wiki`
 - `projects`
 - `packages`（如果目标功能支持）
+- `id-token`（`write`允许请求[OpenID Connect令牌](openid-connect.md)，`read`不授予任何权限）
 
 如果同时指定了`contents`和更细粒度的权限范围（如`code`或`releases`），则该单元以更细粒度的权限范围为准。
 
@@ -65,7 +66,7 @@ permissions:
 ### 兼容性说明
 
 Gitea支持GitHub Actions权限范围的一个子集。
-Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`id-token`、`security-events`和`pages`等GitHub专有的权限范围。
+Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围。
 
 Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不作为独立的权限范围存在：
 
@@ -82,16 +83,19 @@ Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不
 - **宽松**：对Job所属仓库的大多数单元拥有读写权限（向后兼容的默认值）。
 - **受限**：对Job所属仓库的`code`、`releases`和`packages`拥有只读权限，默认无权访问其他单元。
 
+两种模式都不包含`id-token`。
+
 <a id="maximum-token-permissions-clamping"></a>
 ## 最大令牌权限（限制）
 
-您可以为每个仓库单元配置最大权限。
+您可以为每个仓库单元以及`id-token`配置最大权限。
 Job的实际权限按以下方式计算：
 
 `effective = min(requested, maximum)`
 
 这意味着工作流可以降低Job的权限，但不能超过您配置的最大权限。
 如果未配置最大权限，则所有权限范围的最大权限默认为`write`。
+在Gitea支持`id-token`之前保存的最大权限会拒绝`id-token`，直到您将其设为`write`。
 
 <a id="where-to-configure"></a>
 ## 配置位置
@@ -107,7 +111,7 @@ Job的实际权限按以下方式计算：
 <a id="fork-pull-requests"></a>
 ## Fork拉取请求
 
-出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。
+出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。这些Job也无法获取OpenID Connect令牌。
 
 <a id="cross-repository-access"></a>
 ## 跨仓库访问