Merge branch 'main' into lunny/add_project_workflow

2026-11-08 11:00:34 +00:00 · 2026-10-22 23:22:15 +00:00
commit c902fe9253
@@ -1,8 +0,0 @@
-{
-  "sidebar.docs.category.actions": {
-    "message": "Actions"
-  },
-  "sidebar.docs.category.packages": {
-    "message": "Packages"
-  }
-}
@@ -1,8 +0,0 @@
-{
-  "outdated.message": {
-    "message": "当前中文文档翻译不是最新版，访问英文版本查看最新内容，或"
-  },
-  "outdated.help": {
-    "message": "帮助我们翻译"
-  }
-}
@@ -2,8 +2,9 @@
 date: "2023-05-23T09:00:00+08:00"
 slug: adding-legal-pages
 sidebar_position: 110
+
 aliases:
-  - /zh-tw/adding-legal-pages
+  - /zh-cn/adding-legal-pages
 ---

 # 添加法律页面
@@ -12,10 +13,10 @@ aliases:

 ## 获取页面

-Gitea 源代码附带了示例页面，位于 `contrib/legal` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如，如果要添加隐私政策：
+Gitea 源代码附带了示例页面，位于 `contrib/service/sample-page` 目录中。将它们复制到 `custom/public/assets/` 目录下。例如，如果要添加隐私政策：

 ```
-wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/legal/privacy.html.sample
+wget -O /path/to/custom/public/assets/privacy.html https://raw.githubusercontent.com/go-gitea/gitea/main/contrib/service/sample-page/privacy.html.sample
 ```

 现在，你需要编辑该页面以满足你的需求。特别是，你必须更改电子邮件地址、网址以及与 "Your Gitea Instance" 相关的引用，以匹配你的情况。
@@ -80,7 +80,7 @@ cd gitea-dump-1610949662
 mv app.ini /etc/gitea/conf/app.ini
 mv data/* /var/lib/gitea/data/
 mv log/* /var/lib/gitea/log/
-mv repos/* /var/lib/gitea/repositories/
+mv repos/* /var/lib/gitea/data/gitea-repositories/
 chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea

 # mysql
@@ -0,0 +1,547 @@
+---
+date: "2017-04-15T14:56:00+02:00"
+slug: "customizing-gitea"
+sidebar_position: 100
+
+aliases:
+  - /zh-cn/customizing-gitea
+---
+
+# 自定义 Gitea
+
+自定义 Gitea 通常通过 `CustomPath` 目录完成。默认情况下，它是工作目录（WorkPath）下的
+`custom` 目录，但如果您的[安装方式](../installation/from-binary.md)做了不同设置，也可能位于其他位置。
+这是覆盖配置项、模板等内容的核心位置。您可以通过 `gitea help` 查看 `CustomPath`，也可以在
+_站点管理_ 页面的 _Configuration_ 选项卡中找到该路径。您还可以通过设置 `GITEA_CUSTOM`
+环境变量，或在 `gitea` 二进制上使用 `--custom-path` 选项来覆盖 `CustomPath`。
+（命令行选项会覆盖环境变量。）
+
+如果 Gitea 以二进制方式部署，所有默认路径都相对于 Gitea 二进制文件。
+如果通过发行版安装，这些路径通常会按照 Linux 文件系统标准进行调整。Gitea 会尝试创建所需目录，
+包括 `custom/`。某些发行版可能会通过 `/etc/gitea/` 为 `custom` 提供一个符号链接。
+
+应用配置可以在 `CustomConf` 文件中找到，默认路径为 `$GITEA_CUSTOM/conf/app.ini`，
+但如果您的[安装方式](../installation/from-binary.md)修改了配置，也可能位于其他位置。
+同样，您可以通过 `gitea help` 查看该变量，也可以使用 `gitea` 二进制的 `--config` 选项覆盖它。
+
+- [快速备忘单](../administration/config-cheat-sheet.md)
+- [完整配置清单](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini)
+
+如果在检查 `gitea help` 后仍找不到 `CustomPath` 目录，请检查 `GITEA_CUSTOM` 环境变量；
+它可以用来将默认路径覆盖为其他位置。例如，`GITEA_CUSTOM` 可能由 init 脚本设置。
+您也可以在站点管理页面的 “Configuration” 选项卡下检查该值是否已设置。
+
+- [环境变量清单](../administration/environment-variables.md)
+
+:::note
+Gitea 必须执行完整重启后，配置更改才会生效。
+:::
+
+## 提供自定义公共文件
+
+要让 Gitea 提供自定义公共文件（例如页面和图片），请将 `$GITEA_CUSTOM/public/`
+目录作为 webroot。Gitea 会跟随符号链接。
+当前仅提供以下文件：
+
+- `public/robots.txt`
+- `public/.well-known/` 目录中的文件
+- `public/assets/` 目录中的文件
+
+例如，存放在 `$GITEA_CUSTOM/public/assets/` 中的 `image.png` 文件，可以通过
+`http://gitea.domain.tld/assets/image.png` 访问。
+
+## 修改 Logo
+
+如果要构建自定义 logo 和/或 favicon，请克隆 Gitea 源码仓库，替换 `assets/logo.svg`
+和/或 `assets/favicon.svg`，然后运行 `make generate-images`。`assets/favicon.svg`
+仅用于 favicon。执行后会更新以下输出文件，随后您可以将它们放到服务器上的
+`$GITEA_CUSTOM/public/assets/img` 中：
+
+- `public/assets/img/logo.svg` - 用于站点图标、应用图标
+- `public/assets/img/logo.png` - 用于 Open Graph
+- `public/assets/img/avatar_default.png` - 用作默认头像图片
+- `public/assets/img/apple-touch-icon.png` - 用于 iOS 设备书签
+- `public/assets/img/favicon.svg` - 用于 favicon
+- `public/assets/img/favicon.png` - 用作不支持 SVG favicon 的浏览器回退图标
+
+如果源图片不是矢量格式，您可以尝试使用诸如[这个工具](https://www.aconvert.com/image/png-to-svg/)
+将光栅图像转换为矢量图。
+
+## 自定义 Gitea 页面和资源
+
+Gitea 可执行文件内置了运行所需的全部资源：模板、图片、样式表和翻译。您可以在 `custom`
+目录下放置与原路径一致的替换文件来覆盖其中任意资源。例如，要替换 C++ 仓库默认提供的
+`.gitignore`，我们需要替换 `options/gitignore/C++`。为此，您必须将替换文件放到
+`$GITEA_CUSTOM/options/gitignore/C++`（`CustomPath` 目录位置见本文开头说明）。
+
+Gitea 的每一个页面都可以修改。动态内容通过 [go template](https://pkg.go.dev/html/template)
+生成，您可以通过在 `$GITEA_CUSTOM/templates` 目录下放置替换文件进行修改。
+
+要获取任意内嵌文件（包括模板），可以使用[`gitea embedded` 工具](../administration/cmd-embedded.md)。
+另外，也可以在 Gitea 源码仓库的 [`templates`](https://github.com/go-gitea/gitea/tree/main/templates)
+目录中找到它们。（注意：示例链接指向 `main` 分支，请确保所使用的模板与您当前的发布版本兼容。）
+
+请注意，任何包含在 `{{` 和 `}}` 中的语句都是 Gitea 的模板语法，
+如果您没有完全理解这些组件，就不应修改它们。
+
+### 自定义首页 / 主页
+
+将与您所使用 Gitea 版本对应的 [`home.tmpl`](https://github.com/go-gitea/gitea/blob/main/templates/home.tmpl)
+从 `templates` 目录复制到 `$GITEA_CUSTOM/templates`。
+随后按您的需要编辑即可。
+不要忘记重启 Gitea 以应用更改。
+
+### 添加链接和页签
+
+如果您只是想为顶部导航栏或页脚添加额外链接，或者为仓库视图添加额外页签，
+可以将它们分别放入 `$GITEA_CUSTOM/templates/custom/` 目录中的
+`extra_links.tmpl`（添加到导航栏的链接）、`extra_links_footer.tmpl`
+（添加到页脚左侧的链接）和 `extra_tabs.tmpl`。
+
+例如，假设您在德国，需要添加法律上通常要求提供的 “Impressum”/关于页面，用来说明谁对站点内容负责：
+只需将该页面放到 `$GITEA_CUSTOM/public/assets/` 目录中
+（例如 `$GITEA_CUSTOM/public/assets/impressum.html`），再在
+`$GITEA_CUSTOM/templates/custom/extra_links.tmpl` 或
+`$GITEA_CUSTOM/templates/custom/extra_links_footer.tmpl` 中加入指向它的链接即可。
+
+为了匹配当前样式，该链接应使用类名 `item`，并且您可以使用 `{{AppSubUrl}}` 获取基础 URL：
+`<a class="item" href="{{AppSubUrl}}/assets/impressum.html">Impressum</a>`
+
+更多信息请参见[添加法律页面](../administration/adding-legal-pages.md)。
+
+您也可以用同样的方式添加新页签，将其放入 `extra_tabs.tmpl` 中。
+与其他页签样式匹配所需的精确 HTML 位于文件 `templates/repo/header.tmpl`
+（[GitHub 源码](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl)）。
+
+### 页面中的其他插入内容
+
+除了 `extra_links.tmpl` 和 `extra_tabs.tmpl` 之外，您还可以在
+`$GITEA_CUSTOM/templates/custom/` 目录中放置其他有用的模板：
+
+- `header.tmpl`，位于 `<head>` 结束标签之前，例如可用于添加自定义 CSS 文件。
+- `body_outer_pre.tmpl`，位于 `<body>` 起始标签之后。
+- `body_inner_pre.tmpl`，位于顶部导航栏之前，但已处于主容器 `<div class="full height">` 内部。
+- `body_inner_post.tmpl`，位于主容器结束之前。
+- `body_outer_post.tmpl`，位于底部 `<footer>` 元素之前。
+- `footer.tmpl`，位于 `<body>` 结束标签之前，是放置额外 JavaScript 的合适位置。
+
+### 使用 Gitea 变量
+
+您可以在自定义模板中使用各种 Gitea 变量。
+
+首先，_临时_ 启用开发模式：在 `app.ini` 中将 `RUN_MODE = prod` 改为 `RUN_MODE = dev`。
+然后在任意模板中添加 `{{ $ | DumpVar }}`，重启 Gitea 并刷新对应页面；
+这样会输出所有可用变量。
+
+找到所需数据后，使用对应变量即可；例如，如果您需要仓库名称，可以使用 `{{.Repository.Name}}`。
+
+如果您需要对这些数据做一些转换，而您又不熟悉 Go，一种简单的变通办法是先将数据放入 DOM，
+再添加一小段 JavaScript 脚本来处理它。
+
+### 示例：PlantUML
+
+您可以通过 PlantUML 服务器为 Gitea 的 Markdown 添加 [PlantUML](https://plantuml.com/) 支持。
+数据会被编码后发送到 PlantUML 服务器，再由服务器生成图片。官方在
+http://www.plantuml.com/plantuml 提供了一个在线演示服务器，但如果您（或您的用户）拥有敏感数据，
+则可以改为自建一个 [PlantUML 服务器](https://plantuml.com/server)。要启用 PlantUML 渲染，
+请从 https://gitea.com/davidsvantesson/plantuml-code-highlight 复制 JavaScript 文件，
+并将其放入 `$GITEA_CUSTOM/public/assets/` 目录。然后将以下内容添加到 `$GITEA_CUSTOM/templates/custom/footer.tmpl`：
+
+```html
+<script>
+  $(async () => {
+    if (!$('.language-plantuml').length) return;
+    await Promise.all([
+      $.getScript('https://your-gitea-server.com/assets/deflate.js'),
+      $.getScript('https://your-gitea-server.com/assets/encode.js'),
+      $.getScript('https://your-gitea-server.com/assets/plantuml_codeblock_parse.js'),
+    ]);
+    // Replace call with address to your plantuml server
+    parsePlantumlCodeBlocks("https://www.plantuml.com/plantuml");
+  });
+</script>
+```
+
+随后，您就可以在 Markdown 中添加如下代码块：
+
+```plantuml
+Alice -> Bob: Authentication Request
+Bob --> Alice: Authentication Response
+
+Alice -> Bob: Another authentication Request
+Alice <-- Bob: Another authentication Response
+```
+
+该脚本会检测 `class="language-plantuml"` 的标签，不过您也可以通过为
+`parsePlantumlCodeBlocks` 提供第二个参数来修改这一行为。
+
+### 示例：使用 Online 3D Viewer 预览 CAD 文件
+
+您可以在自己的 Gitea 实例中实现 CAD 文件预览。这个实现使用的是
+[`Online 3D Viewer`](https://github.com/kovacsv/Online3DViewer)。
+
+支持以下 3D 文件格式：
+`3dm`, `3ds`, `3mf`, `amf`, `bim`, `brep`, `dae`, `fbx`, `fcstd`, `glb`,
+`gltf`, `ifc`, `igs`, `iges`, `stp`, `step`, `stl`, `obj`, `off`, `ply`, `wrl`
+（`.gltf` 文件仅支持 v2）
+
+#### 第 1 部分：添加模板
+
+我们需要在 `$GITEA_CUSTOM` 中添加模板。
+该模板需要保存到 `$GITEA_CUSTOM/templates/custom/` 中。
+在这里创建 `footer.tmpl` 文件，并向其中添加以下内容：
+
+```
+nano $GITEA_CUSTOM/templates/custom/footer.tmpl
+```
+
+```html
+<script>
+    function onPageChange() {
+      // Supported 3D file types
+      const fileTypes = ['3dm', '3ds', '3mf', 'amf', 'bim', 'brep', 'dae', 'fbx', 'fcstd', 'glb', 'gltf', 'ifc', 'igs', 'iges', 'stp', 'step', 'stl', 'obj', 'off', 'ply', 'wrl'];
+  
+      // Select matching link
+      const links = Array.from(document.querySelectorAll('a.ui.mini.basic.button'));
+      const link3D = links.find(link => {
+        const href = link.href.toLowerCase();
+        return href.includes('/raw/') && fileTypes.some(ext => href.endsWith(`.${ext}`));
+      });
+  
+	if (link3D) {
+	  const existingScript = document.querySelector('script[src="/assets/o3dv/o3dv.min.js"]');
+
+	  const initializeViewer = () => {
+		const fileUrl = link3D.getAttribute('href');
+
+                const fileView = document.querySelector('.file-view');
+
+		if (!fileView) return;
+
+		// Remove only the old viewer container if it exists
+		const oldView3D = document.getElementById('view-3d');
+		if (oldView3D) {
+		  oldView3D.remove();  // safely remove old viewer container div
+		} else {
+		  // No #view-3d, so remove all children inside .file-view
+		  while (fileView.firstChild) {
+		    fileView.removeChild(fileView.firstChild);
+		  }
+		}
+
+		// Create a new container for the viewer
+		const newView3D = document.createElement('div');
+		  newView3D.id = 'view-3d';
+		  newView3D.style.padding = '0';
+		  newView3D.style.margin = '0';
+		  newView3D.style.flexGrow = '1';
+		  newView3D.style.minHeight = '0';
+		  newView3D.style.width = '100%';
+		
+		const header = document.querySelector('header');
+		const headerHeight = header ? header.offsetHeight : 0;
+
+		newView3D.style.height = `calc(100vh - ${headerHeight}px)`;		
+
+		// Append the new container inside fileView
+		fileView.appendChild(newView3D);
+
+		const parentDiv = document.getElementById('view-3d');
+		if (parentDiv) {
+		  const viewer = new OV.EmbeddedViewer(parentDiv, {
+			backgroundColor: new OV.RGBAColor(59, 68, 76, 0),
+			defaultColor: new OV.RGBColor(200, 200, 200),
+			edgeSettings: new OV.EdgeSettings(false, new OV.RGBColor(0, 0, 0), 1),
+			environmentSettings: new OV.EnvironmentSettings([
+			  '/assets/o3dv/envmaps/fishermans_bastion/negx.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posx.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posy.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/negy.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/posz.jpg',
+			  '/assets/o3dv/envmaps/fishermans_bastion/negz.jpg'
+			], false)
+		  });
+
+		  viewer.LoadModelFromUrlList([fileUrl]);
+		}
+	  };
+
+	  if (typeof OV === 'undefined') {
+		if (!existingScript) {
+		  const script = document.createElement('script');
+		  script.onload = initializeViewer;
+		  script.src = '/assets/o3dv/o3dv.min.js';
+		  document.head.appendChild(script);
+		} else {
+		  // Script is loading but OV not yet ready — wait for it
+		  existingScript.addEventListener('load', initializeViewer);
+		}
+	  } else {
+		// OV already loaded
+		initializeViewer();
+	  }
+	}
+    };
+
+    // Run when the page is fully loaded
+    document.addEventListener('DOMContentLoaded', onPageChange); 
+
+    const targetSelector = 'a.ui.mini.basic.button[href*="/raw/"]';
+    let lastHref = null;
+    let timeoutId = null;
+
+    const checkAndRun = () => {
+      const rawLink = document.querySelector(targetSelector);
+      if (!rawLink) return;
+
+      const currentHref = rawLink.getAttribute('href');
+      if (currentHref !== lastHref) {
+        lastHref = currentHref;
+
+        const fileName = currentHref.split('/').pop();
+        console.log('New Raw file link detected after delay:', fileName);
+        
+        onPageChange();
+      }
+    };
+
+    const observer = new MutationObserver(() => {
+      // Delay execution by 300ms after last mutation
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(checkAndRun, 300);
+    });
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+</script>
+```
+
+#### 第 2 部分：添加公共文件
+
+现在我们需要下载最新版本的 O3DV。进入 `$GITEA_CUSTOM/public/assets/`。
+使用以下命令创建目录（并进入该目录）：
+
+```
+mkdir o3dv
+cd o3dv
+```
+
+从 [`GitHub`](https://github.com/kovacsv/Online3DViewer/releases) 复制最新发行版压缩包链接
+（当前示例版本为 v0.18.0）。
+然后使用例如 wget 或 curl 下载该文件：
+
+```
+wget https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
+```
+
+或者
+
+```
+curl -L -O https://github.com/kovacsv/Online3DViewer/releases/download/0.18.0/o3dv.zip
+```
+
+再使用例如 unzip 解压归档文件：
+```
+unzip o3dv.zip
+```
+
+#### 第 3 部分：目录权限
+
+最后一步，修改 public 目录权限：
+```
+chown -R git:git $GITEA_CUSTOM/public
+```
+
+现在一切就绪！重启您的 Gitea 实例以应用这些更改，并在浏览器中进行测试。
+
+简单检查一下。最终目录结构应类似如下：
+
+```
+$GITEA_CUSTOM/templates
+-- custom
+    `-- footer.tmpl
+
+$GITEA_CUSTOM/public/assets/
+-- o3dv
+   |-- o3dv.zip
+   |-- o3dv.license.md
+   |-- o3dv.min.js
+   |-- envmaps
+    \...
+```
+
+## 自定义 Gitea 邮件
+
+`$GITEA_CUSTOM/templates/mail` 目录允许您修改 Gitea 每一种邮件的正文。
+可被覆盖的模板可以在 Gitea 源码的
+[`templates/mail`](https://github.com/go-gitea/gitea/tree/main/templates/mail)
+目录中找到。
+覆盖方式是将对应文件复制到 `$GITEA_CUSTOM/templates/mail` 下，
+并保持与源码一致的完整路径结构。
+
+任何包含在 `{{` 和 `}}` 中的语句都是 Gitea 的模板语法，
+如果您没有完全理解这些组件，就不应修改它们。
+
+## 为 Gitea 添加统计分析
+
+Google Analytics、Matomo（原 Piwik）以及其他分析服务都可以集成到 Gitea。
+要添加跟踪代码，请参考本文的“页面中的其他插入内容”一节，
+并将相应 JavaScript 添加到 `$GITEA_CUSTOM/templates/custom/header.tmpl` 文件中。
+
+## 自定义 gitignores、labels、licenses、locales 和 readmes
+
+将自定义文件放入 `custom/options` 下对应的子目录中。
+
+:::note
+这些文件不应带有扩展名，例如应使用 `Labels`，而不是 `Labels.txt`
+:::
+
+### gitignores
+
+要添加自定义 `.gitignore`，请在 `$GITEA_CUSTOM/options/gitignore` 中添加一个文件，
+文件内容遵循现有的 [.gitignore 规则](https://git-scm.com/docs/gitignore)。
+
+## 自定义 git 配置
+
+从 Gitea 1.20 开始，您可以通过 `git.config` 区块自定义 git 配置。
+
+### 启用签名 git push
+
+[签名推送](https://git-scm.com/docs/git-push#Documentation/git-push.txt---signedtruefalseif-asked)
+允许客户端对 push 操作本身进行加密签名（而不仅仅是对单个提交签名）。
+要启用签名推送，请将以下内容添加到 `app.ini`：
+
+```ini
+[git.config]
+receive.certNonceSeed = <randomstring>
+```
+
+`certNonceSeed` 应设置为一个随机字符串并妥善保密。它用于生成防重放 nonce。
+Gitea 默认已经设置了 `receive.advertisePushOptions = true`，因此无需额外配置。
+请注意，Gitea 不会读取 `/etc/gitconfig`，因此必须像上面这样通过 `app.ini` 设置该选项。
+
+在客户端侧，可以通过 `git push --signed` 进行签名推送，
+或者使用 `git config --global push.gpgSign if-asked` 永久启用。
+
+### Labels
+
+从 Gitea 1.19 开始，您可以向 `$GITEA_CUSTOM/options/label` 中添加一个遵循
+[YAML 标签格式](https://github.com/go-gitea/gitea/blob/main/options/label/Advanced.yaml)
+的文件：
+
+```yaml
+labels:
+  - name: "foo/bar"  # 下拉列表中显示的标签名称
+    exclusive: true # 是否为作用域标签使用互斥命名空间，作用域分隔符为 /
+    color: aabbcc # 十六进制颜色值
+    description: Some label # 标签用途的详细描述
+ ```
+
+旧的[传统文件格式](https://github.com/go-gitea/gitea/blob/main/options/label/Default)
+仍可使用，格式如下，但我们强烈建议改用新的 YAML 格式。
+
+`#hex-color label name ; label description`
+
+更多信息请参阅[标签文档](../usage/issues-prs/labels.md)。
+
+### Licenses
+
+要添加自定义许可证，请将包含许可证文本的文件添加到 `$GITEA_CUSTOM/options/license`。
+
+### Locales
+
+本地化语言由我们的 [Crowdin](https://crowdin.com/project/gitea) 管理。
+您可以通过将修改后的语言文件放到 `$GITEA_CUSTOM/options/locale` 中来覆盖某个语言环境。
+Gitea 默认的语言文件可以在源码目录
+[`options/locale`](https://github.com/go-gitea/gitea/tree/main/options/locale) 中找到，
+这些文件可以作为您修改时的参考示例。
+
+如果要添加一个全新的语言环境，除了将文件放到上述位置外，
+您还需要在 `app.ini` 的 `[i18n]` 部分中添加新的语言代码和名称。
+请记住，Gitea 会将这些设置视为**覆盖项**，因此如果您还想保留其他语言，
+就需要复制默认值并在其中加入您自己的语言项。
+
+```ini title="app.ini"
+[i18n]
+LANGS = en-US,foo-BAR
+NAMES = English,FooBar
+```
+
+如果用户浏览器的语言与列表中的任何语言都不匹配，则第一种语言会被用作默认语言。
+
+不同版本之间的语言文件可能会变化，因此强烈建议持续跟踪您自定义过的语言文件。
+
+### Readmes
+
+要添加自定义 Readme，请将一个 Markdown 格式的文件（不带 `.md` 扩展名）
+放到 `$GITEA_CUSTOM/options/readme` 中。
+
+:::note
+Readme 模板支持**变量展开**。
+当前可用变量包括 `{Name}`（仓库名称）、`{Description}`、`{CloneURL.SSH}`、`{CloneURL.HTTPS}` 和 `{OwnerName}`
+:::
+
+### Reactions
+
+要修改反应表情，您可以在 `app.ini` 中设置允许使用的 reactions。
+
+```ini title="app.ini"
+[ui]
+REACTIONS = +1, -1, laugh, confused, heart, hooray, eyes
+```
+
+完整的受支持 emoji 列表见 [emoji list](https://gitea.com/gitea/gitea.com/issues/8)。
+
+## 自定义 Gitea 外观
+
+内置主题有 `gitea-light`、`gitea-dark` 和 `gitea-auto`
+（会自动适应操作系统设置）。
+
+默认主题可以通过 `app.ini` 中 [ui](../administration/config-cheat-sheet.md#界面) 部分的
+`DEFAULT_THEME` 进行修改。
+
+Gitea 还支持用户主题，这意味着每位用户都可以选择要使用的主题。
+用户可选主题列表可以通过 `app.ini` 中 [ui](../administration/config-cheat-sheet.md#界面)
+部分的 `THEMES` 值进行配置。
+
+要让所有用户都能使用自定义主题：
+
+1. 将 CSS 文件添加到 `$GITEA_CUSTOM/public/assets/css/theme-<theme-name>.css`。
+   您可以通过执行 `gitea help` 并查看其中的 “CustomPath” 值来确认实例的 `$GITEA_CUSTOM`。
+2. 将 `<theme-name>` 添加到 `app.ini` 中 `THEMES` 设置的逗号分隔列表中，
+   或者将 `THEMES` 留空以允许所有主题。
+
+名为 `theme-my-theme.css` 的自定义主题文件会在用户主题选择页面中显示为 `my-theme`。
+您还可以在自定义主题 CSS 文件中加入主题元信息，以提供更多说明。
+如果自定义主题是暗色主题，请在 `:root` 块中设置全局 CSS 变量 `--is-dark-theme: true`。
+这样 Gitea 就可以相应地调整 Monaco 代码编辑器的主题。
+如果要实现 “auto” 主题，可以参考 `theme-gitea-auto.css`。
+
+```css
+gitea-theme-meta-info {
+  --theme-display-name: "My Awesome Theme"; /* this theme will be display as "My Awesome Theme" on the UI */
+}
+:root {
+  --is-dark-theme: true; /* if it is a dark theme */
+  --color-primary: #112233;
+  /* more custom theme variables ... */
+}
+```
+
+社区主题列在 [gitea/awesome-gitea#themes](https://gitea.com/gitea/awesome-gitea#themes)。
+
+默认主题源码可在[这里](https://github.com/go-gitea/gitea/blob/main/web_src/css/themes)找到。
+
+## 自定义字体
+
+可以使用 CSS 变量自定义字体：
+
+```css
+:root {
+  --fonts-proportional: /* custom proportional fonts */ !important;
+  --fonts-monospace: /* custom monospace fonts */ !important;
+  --fonts-emoji: /* custom emoji fonts */ !important;
+}
+```
@@ -3,7 +3,7 @@ date: "2018-05-22T11:00:00+00:00"
 slug: "reverse-proxies"
 sidebar_position: 16
 aliases:
-  - /zh-tw/reverse-proxies
+  - /zh-cn/reverse-proxies
 ---

 # 反向代理
@@ -14,6 +14,8 @@ aliases:
 2. 将 `https://git.example.com/foo` 反向代理到 `http://gitea:3000/foo`
 3. 确保反向代理不会解码 URI。`https://git.example.com/a%2Fb`的请求应该被传递给 `http://gitea:3000/a%2Fb`。
 4. 确保 `Host` 和 `X-Forwarded-Proto` 头被正确的传递给 Gitea，使 Gitea 可以看到正在访问的真实 URL。
+5. 确保 Web 服务器有完整的证书（包括所有中间证书和根证书），以便 `git clone` 和 `git pull` 正常工作。
+6. Gitea 会在 `/-/ws` 使用 WebSocket 连接，用于通知计数等实时更新。请确保反向代理使用 HTTP/1.1，并转发 `Upgrade` 和 `Connection` 头，参见下面的示例。否则 Gitea 会回退为定期轮询。

 ## 使用子路径

@@ -39,6 +41,7 @@ server {
    location / {
        client_max_body_size 512M;
        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
@@ -61,8 +64,9 @@ server {

        # 确保 nginx 使用未转义 URI， 按原样保持 "%2F"。 确保 nginx 去除 "/gitea" 子路径前缀， 按原样传递 "/v2"。
        rewrite ^ $request_uri;
-        rewrite ^(/gitea)?(/.*) $2 break;
+        rewrite ^/(gitea($|/))?(.*) /$3 break;
        proxy_pass http://127.0.0.1:3000$uri;
+        proxy_http_version 1.1;

        # 其他的常规 HTTP 表头，见上面“使用 Nginx 作为反向代理服务”小节的配置
        proxy_set_header Connection $http_connection;
@@ -107,6 +111,7 @@ server {
    }

    location / {
+        # 其他指令见上面「使用 Nginx 作为反向代理服务」小节
        proxy_pass http://localhost:3000;
    }
 }
@@ -123,6 +128,7 @@ server {
    server_name git.example.com;

    location / {
+        # 其他指令见上面「使用 Nginx 作为反向代理服务」小节
        proxy_pass http://localhost:3000;
    }
 }
@@ -144,6 +150,20 @@ server {
 }
 ```

+## Nginx Proxy Manager
+
+如果使用 Nginx Proxy Manager 作为 Gitea 的反向代理，配置与原生 Nginx 略有不同。
+
+它会[默认给自定义 location 加上一些指令](https://github.com/NginxProxyManager/nginx-proxy-manager/blob/master/docker/rootfs/etc/nginx/conf.d/include/proxy.conf)，因此上面 Nginx 配置里对应的指令不要再写一遍。否则会因为指令重复（尤其是 `proxy_set_header Host $host`）出现 `400 bad request`。
+
+创建 `/` 自定义 location 时，只需在其配置中加入：
+
+```nginx
+client_max_body_size 512M;
+```
+
+在代理主机上启用 `Websockets Support`，Nginx Proxy Manager 会自行加入 WebSocket 相关指令。再额外添加 `proxy_http_version` 会导致 Nginx 拒绝启动。
+
 ## 使用 Apache HTTPD 作为反向代理服务

 如果您想使用 Apache HTTPD 作为 Gitea 的反向代理服务，您可以为您的 Apache HTTPD 作如下配置（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：
@@ -154,30 +174,23 @@ server {
    ProxyPreserveHost On
    ProxyRequests off
    AllowEncodedSlashes NoDecode
-    ProxyPass / http://localhost:3000/ nocanon
+    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
 ```

-注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
+:::note
+必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。
+
+`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本。更旧的版本**必须**去掉它，否则 Apache HTTPD 将无法启动。
+:::
+
+如果希望用 Let's Encrypt 的 webroot 验证，请在 `ProxyPass` 之前加入 `ProxyPass /.well-known !`，避免把这些请求代理到 Gitea。

 ## 使用 Apache HTTPD 作为反向代理服务并将 Gitea 路由至一个子路径

 如果您已经有一个域名并且想与 Gitea 共享该域名，您可以增加以下配置为 Gitea 添加路由规则（在 Ubuntu 中，配置文件通常在 `/etc/apache2/httpd.conf` 目录下）：

-```
-<VirtualHost *:80>
-    ...
-    <Proxy *>
-         Order allow,deny
-         Allow from all
-    </Proxy>
-    AllowEncodedSlashes NoDecode
-    # 注意: 路径和 URL 后面都不要写路径符号 '/'
-    ProxyPass /git http://localhost:3000 nocanon
-</VirtualHost>
-```
-
 ```apacheconf
 <VirtualHost *:80>
    ...
@@ -187,7 +200,7 @@ server {
    </Proxy>
    AllowEncodedSlashes NoDecode
    # 注意: 路径和 URL 后面都不要写路径符号 '/'
-    ProxyPass /git http://localhost:3000 nocanon
+    ProxyPass /git http://localhost:3000 nocanon upgrade=websocket
    ProxyPreserveHost On
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
 </VirtualHost>
@@ -195,7 +208,55 @@ server {

 然后您**必须**在 Gitea 的配置文件中正确的添加类似 `[server] ROOT_URL = http://git.example.com/git/` 的配置项。

-注：必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`
+:::note
+必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
+:::
+
+## 使用 Apache HTTPD 直接提供静态资源
+
+我们可以通过将资源分为静态和动态两种类型来调节性能。
+
+CSS 文件、JavaScript 文件、图片和字体是静态内容。首页、仓库视图和工单列表是动态内容。
+
+Apache HTTPD 可以直接提供静态资源，并且只代理动态资源请求给 Gitea。
+
+将 Gitea 源代码仓库的一个快照下载到 `/path/to/gitea/`。
+在此之后，在本地仓库目录运行 `make frontend` 来生成静态资源。在这个情况下，我们只对 `public/` 目录感兴趣，您可以删除剩下的其他目录。
+（为了生成静态资源，您需要安装一个[带 npm 的 Node ](https://nodejs.org/en/download/)和 `make`）
+
+取决于您的用户量的大小，您可以将流量分离到两个不同的服务器，或者为静态资源配置一个 cdn。
+
+### 单服务器节点，单域名
+
+将 `[server] STATIC_URL_PREFIX = /_/static` 写入您的 Gitea 配置文件：
+
+```apacheconf
+<VirtualHost *:80>
+    ...
+    <Proxy *>
+         Order allow,deny
+         Allow from all
+    </Proxy>
+
+    ProxyPass /_/static/ !
+    Alias /_/static/ /path/to/gitea/public/
+    <Directory /path/to/gitea/public/>
+        Options FollowSymlinks
+		AllowOverride None
+		Require all granted
+    </Directory>
+
+    AllowEncodedSlashes NoDecode
+    # 注意: 路径和 URL 后面都不要写路径符号 '/'
+    ProxyPass / http://localhost:3000/ nocanon upgrade=websocket
+    ProxyPreserveHost On
+    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+</VirtualHost>
+```
+
+:::note
+必须启用以下 Apache HTTPD 组件：`proxy`， `proxy_http`。`upgrade=websocket` 需要 Apache HTTPD 2.4.48 或更高版本，更旧的版本请去掉它。
+:::

 ## 使用 Caddy 作为反向代理服务

@@ -231,11 +292,13 @@ git.example.com {

 - 使用 Microsoft Web Platform Installer 5.1 (WebPI) 安装 Application Request Routing（简称 ARR），或者在 [IIS.net](https://www.iis.net/downloads/microsoft/application-request-routing) 下载这个插件。
 - 一但这个模块被安装到 IIS 上，你将会在 IIS 管理控制台看到一个叫做 URL Rewrite 的新图标。
+- 安装 Windows 功能 `WebSocket Protocol`，否则 ARR 无法代理 Gitea 的 WebSocket 端点。
 - 打开 IIS 管理控制台，在左边的列表中点击 `Gitea Proxy` 网页。在中间选中并且双击 URL Rewrite 的图标来加载 URL 重写的面板。
 - 在管理控制台的右边选择 `Add Rule` 操作，并且在 `Inbound and Outbound Rules` 分类中选择 `Reverse Proxy Rule`。
 - 在 Inbound Rules 中， 将 server name 设置为 Gitea 正在运行的主机以及对应端口。例如，如果你在 localhost 的 3000 端口上运行 Gitea，则设置为 `127.0.0.1:3000`。
 - 启用 SSL Offloading
 - 在 Outbound Rules 中，确保设置了 `Rewrite the domain names of the links in HTTP response`，并且将 `From:` 设置为上面的 server name，将 `To:` 设置为你的外部访问名称，例如：`git.example.com`
+- 关闭 Application Request Routing 的 `Server Proxy Settings` 中的 `Reverse rewrite host in response headers`（在 IIS 管理器中选择服务器节点，打开 `Application Request Routing Cache`，再打开右侧的 `Server Proxy Settings`）。若保持开启，ARR 会把 `Location` 头里的主机改回内部地址，导致登录或表单提交后的重定向把浏览器送到 `127.0.0.1:3000` 而不是 `git.example.com`。
 - 现在，根据下面的内容为您的网页编辑 `web.config`（将 `127.0.0.1:3000` 和 `git.example.com` 改为适当的值）

 ```xml
@@ -3,7 +3,7 @@ date: "2018-06-24:00:00+02:00"
 slug: "api-usage"
 sidebar_position: 40
 aliases:
-  - /zh-tw/api-usage
+  - /zh-cn/api-usage
 ---

 # API 使用指南
@@ -12,6 +12,7 @@ aliases:

 通常情况下， `ENABLE_SWAGGER` 默认开启并且参数 `MAX_RESPONSE_ITEMS` 默认为 50。您可以从 [Config Cheat Sheet](../administration/config-cheat-sheet.md) 中获取更多配置相关信息。

+<a id="authentication"></a>
 ## 通过 API 认证

 Gitea 支持以下几种 API 认证方式：
@@ -1,20 +1,18 @@
 ---
 date: "2016-12-01T16:00:00+02:00"
-
 slug: "install-from-source"
 sidebar_position: 30
-
 aliases:
-  - /zh-tw/install-from-source
+  - /zh-cn/install-from-source
 ---

 # 使用源代码安装

 你需要 [安装 Go](https://golang.google.cn/doc/install) 并正确设置 Go 环境。特别的，建议设置`$GOPATH`环境变量，并将 Go 的二进制目录或目录`${GOPATH//://bin:}/bin`添加到`$PATH`中。请参阅 Go 百科上关于 [GOPATH](https://github.com/golang/go/wiki/GOPATH) 的词条。

-接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-tw/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。
+接下来，[安装 Node.js 和 npm](https://nodejs.org/zh-cn/download/)， 这是构建 JavaScript 和 CSS 文件所需的。最低支持的 Node.js 版本是 @minNodeVersion@，建议使用最新的 LTS 版本。

-**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](development/hacking-on-gitea.md) 中给出的建议。
+**注意**：需要 Go 版本 @minGoVersion@ 或更高版本。不过，建议获取与我们的持续集成（continuous integration, CI）相同的版本，请参阅在 [Hacking on Gitea](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md) 中给出的建议。

 ## 下载

@@ -54,8 +52,8 @@ git checkout @sourceVersion@  # or git checkout pr-xyz
 要从源代码进行构建，系统必须预先安装以下程序：

 - `go` @minGoVersion@ 或更高版本，请参阅 [这里](https://go.dev/dl/)
- `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-tw/download/)
- `make`, 请参阅 [这里](development/hacking-on-gitea.md)
+- `node` @minNodeVersion@ 或更高版本，并且安装 `npm`, 请参阅 [这里](https://nodejs.org/zh-cn/download/)
+- `make`, 请参阅 [这里](https://github.com/go-gitea/gitea/blob/main/docs/build-setup.md)

 为了尽可能简化编译过程，提供了各种 [make 任务](https://github.com/go-gitea/gitea/blob/main/Makefile)。

@@ -83,7 +81,7 @@ TAGS="bindata sqlite sqlite_unlock_notify" make build
 `build`目标分为两个子目标：

 - `make backend` 需要 [Go @minGoVersion@](https://golang.google.cn/doc/install) 或更高版本。
- `make frontend` 需要 [Node.js @minNodeVersion@](https://nodejs.org/zh-tw/download/) 或更高版本。
+- `make frontend` 需要 [Node.js @minNodeVersion@](https://nodejs.org/zh-cn/download/) 或更高版本。

 如果存在预构建的前端文件，可以仅构建后端：

@@ -3,7 +3,7 @@ date: "2017-07-21T12:00:00+02:00"
 slug: "linux-service"
 sidebar_position: 40
 aliases:
-  - /zh-tw/linux-service
+  - /zh-cn/linux-service
 ---

 # 在 Linux 中以 service 方式运行
@@ -18,7 +18,7 @@ aliases:
 sudo vim /etc/systemd/system/gitea.service
 ```

-接着拷贝示例代码 [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/systemd/gitea.service) 并取消对任何需要运行在主机上的服务部分的注释，譬如 MySQL。
+接着拷贝示例代码 [gitea.service](https://github.com/go-gitea/gitea/blob/main/contrib/service/systemd/gitea.service) 并取消对任何需要运行在主机上的服务部分的注释，譬如 MySQL。

 修改 user，home 目录以及其他必须的初始化参数，如果使用自定义端口，则需修改 PORT 参数，反之如果使用默认端口则需删除 -p 标记。

@@ -51,7 +51,7 @@ sudo vim /etc/supervisor/supervisord.conf
 ```

 增加如下示例配置
-[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/supervisor/gitea)。
+[supervisord config](https://github.com/go-gitea/gitea/blob/main/contrib/service/supervisor/gitea)。

 将 user(git) 和 home(/home/git) 设置为与上文部署中匹配的值。如果使用自定义端口，则需修改 PORT 参数，反之如果使用默认端口则需删除 -p 标记。

@@ -3,7 +3,7 @@ date: "2020-02-09T20:00:00+02:00"
 slug: "install-with-docker-rootless"
 sidebar_position: 60
 aliases:
-  - /zh-tw/install-with-docker-rootless
+  - /zh-cn/install-with-docker-rootless
 ---

 # 使用 Docker 安装 (rootless)
@@ -53,7 +53,7 @@ sudo chown 1000:1000 config/ data/

 > 如果未为卷设置正确的权限，容器可能无法启动。

-对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:dev-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-dev-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.16-dev-rootless`）。
+对于稳定版本，您可以使用 `:latest-rootless`、`:1-rootless`，或指定特定的版本，如: `@dockerVersion@-rootless`。如果您想使用最新的开发版本，则可以使用 `:main-nightly-rootless` 标签。如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly-rootless` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly-rootless`）。

 ## 自定义端口

@@ -3,7 +3,7 @@ date: "2016-12-01T16:00:00+02:00"
 slug: "install-with-docker"
 sidebar_position: 70
 aliases:
-  - /zh-tw/install-with-docker
+  - /zh-cn/install-with-docker
 ---

 # 使用 Docker 安装
@@ -14,7 +14,7 @@ Gitea 在其 Docker Hub 组织内提供自动更新的 Docker 镜像。可以始

 ## 基本

-最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 将安装当前的开发版本。对于稳定的发行版，您可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。
+最简单的设置只是创建一个卷和一个网络，然后将 `docker.gitea.com/gitea:latest` 镜像作为服务启动。由于没有可用的数据库，因此可以使用 SQLite3 初始化数据库。创建一个类似 `gitea` 的目录，并将以下内容粘贴到名为 `docker-compose.yml` 的文件中。请注意，该卷应由配置文件中指定的 UID/GID 的用户/组拥有。如果您不授予卷正确的权限，则容器可能无法启动。另请注意，标签 `:latest` 安装的是最新的稳定版本。对于稳定的发行版，您也可以使用 `:1` 或指定某个发行版，例如 `@dockerVersion@`。如果您想使用最新的开发版本，则可以使用 `:main-nightly` 标签；如果您想运行发布分支的最新提交，可以使用 `:1.x-nightly` 标签，其中 x 是 Gitea 的次要版本号（例如:`1.27-nightly`）。

 ```yaml
 version: "3"
@@ -296,7 +296,6 @@ docker run -it --rm docker.gitea.com/gitea:1 gitea generate secret INTERNAL_TOKE
 ```

 ```yaml
-
 ---
 services:
  server:
@@ -0,0 +1,102 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "comparison"
+sidebar_position: 15
+---
+
+# 与GitHub Actions的对比
+
+Gitea Actions旨在与GitHub Actions兼容，差异如下。
+
+## 额外功能
+
+<a id="absolute-action-urls"></a>
+### Action URL绝对路径
+
+`uses:`支持指向任意Git托管平台的绝对URL，例如`uses: https://gitea.com/actions/checkout@v4`。
+
+<a id="action-prefixes"></a>
+### Action前缀
+
+`uses:`支持以下前缀：
+
+- `self:`引用您自己的Gitea实例，例如`uses: self:owner/repo@v1`或`uses: self:owner/repo/.gitea/workflows/build.yml@v1`
+- `builtin:`运行Gitea Runner内置的Action，无需下载，Job镜像中也无需Node，例如`uses: builtin:checkout`
+
+`builtin:checkout`支持`actions/checkout`的`repository`、`ref`、`token`、`path`和`fetch-depth`输入，默认值相同，其他输入会使步骤失败。
+
+<a id="workflow-relative-actions"></a>
+### 相对于工作流的Actions
+
+`$/`引用工作流所在的仓库和提交，或外层复合Action所在的仓库和提交，例如`uses: $/.gitea/actions/build`。
+与`./`不同，它无需事先检出代码。
+
+### 使用Go编写Actions
+
+请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
+
+### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
+
+`schedule`还支持`@yearly`、`@monthly`、`@weekly`、`@daily`和`@hourly`，而[GitHub不支持](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule)。
+
+## 不支持的工作流语法
+
+### `jobs.<job_id>.environment`
+
+[`jobs.<job_id>.environment`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)会被忽略。
+
+### 复杂的`runs-on`
+
+[`runs-on`](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)支持：
+
+- 静态字符串：`runs-on: self-hosted`
+- 标签数组：`runs-on: [linux, self-hosted]`
+- 字符串表达式：`runs-on: ${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}`
+- 包含表达式的数组：`runs-on: [linux, "${{ github.event_name == 'push' && 'ubuntu-latest' || 'self-hosted' }}"]`
+
+## 缺失的功能
+
+### 软件包仓库授权
+
+`GITEA_TOKEN`无法发布到其所属仓库的软件包注册表，例如无法推送OCI镜像。
+请改用个人访问令牌，参见[此问题](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692)。
+
+### 问题匹配器
+
+[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)会被忽略。
+
+### 为错误创建注释
+
+[错误注释](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)会被忽略。
+
+### 表达式
+
+[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions)支持GitHub的标准函数和上下文。
+
+## 缺失的UI功能
+
+### 预处理和后处理步骤
+
+预处理和后处理步骤在Job日志中没有单独的区块。
+
+### 服务步骤
+
+服务步骤在Job日志中没有单独的区块。
+
+## 不一样的行为
+
+### `permissions`和`jobs.<job_id>.permissions`
+
+`permissions`和`jobs.<job_id>.permissions`控制`GITEA_TOKEN`的权限，该权限受仓库和所有者设置的限制，并在fork拉取请求和跨仓库访问时受到进一步限制。
+不支持`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
+
+未指定主机的Actions（如`uses: actions/checkout@v4`）会从`https://github.com`下载，当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载。
+请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
+其他来源请参阅[Action URL绝对路径](#absolute-action-urls)、[Action前缀](#action-prefixes)和[相对于工作流的Actions](#workflow-relative-actions)。
+
+### 上下文可用性
+
+不检查[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)，因此`env`等上下文可以在更多地方使用。
@@ -8,46 +8,22 @@ sidebar_position: 40

 Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。

-## Act
+## Gitea Runner

-[nektos/act](https://github.com/nektos/act) 项目是一个优秀的工具，允许你在本地运行GitHub Actions。
-我们受到了它的启发，并思考它是否可能为Gitea运行Actions。
+Gitea Runner部分基于[nektos/act](https://github.com/nektos/act)的硬分支。

-然而，尽管[nektos/act](https://github.com/nektos/act)被设计为一个命令行工具，但我们实际上需要的是一个专为Gitea修改的Go库。
-因此，我们在[gitea/act](https://gitea.com/gitea/act)基础上进行了分叉。
-
-这是一个软分叉，将定期跟进上游。
-虽然添加了一些自定义提交，但我们会尽力避免对原始代码进行太多更改。
-
-分叉的 act 只是Gitea特定用途的桥接或适配器。
-还添加了一些额外的提交，例如：
-
- 将执行日志输出到日志记录器钩子，以便报告给Gitea
- 禁用 GraphQL URL，因为Gitea不支持它
- 每个Job启动一个新的容器，而不是重复使用，以确保隔离性。
-
-这些修改没有理由合并到上游。
-如果用户只想在本地运行可信的Actions，它们是没有意义的。
-
-然而，将来可能会出现重叠，例如两个项目都需要的必要错误修复或新功能。
-在这些情况下，我们将向上游仓库贡献变更。
-
-## act runner
-
-Gitea的Runner被称为act runner，因为它基于act。
-
-与其他CIRunner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。
+与其他CI Runner一样，我们将其设计为Gitea的外部部分，这意味着它应该在与Gitea不同的服务器上运行。

 为了确保Runner连接到正确的Gitea实例，我们需要使用令牌注册它。
 此外，Runner通过声明自己的标签向Gitea报告它可以运行的Job类型。

 之前，我们提到工作流文件中的 `runs-on: ubuntu-latest` 表示该Job将在具有`ubuntu-latest`标签的Runner上运行。
 但是，Runner如何知道要运行 `ubuntu-latest`？答案在于将标签映射到环境。
-这就是为什么在注册过程中添加自定义标签时，需要输入一些复杂内容，比如`my_custom_label:docker://centos:7`。
+这就是为什么Runner的每个标签都会指定一个环境，比如`my_custom_label:docker://centos:7`。
 这意味着Runner可以接受需要在`my_custom_label`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。

 然而，Docker不是唯一的选择。
-act 也支持直接在主机上运行Job。
+Runner 也支持直接在主机上运行Job。
 这是通过像`linux_arm:host`这样的标签实现的。
 这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。

@@ -59,32 +35,31 @@ act 也支持直接在主机上运行Job。
 - `my_custom_label:docker://node:18`：使用`node:18 Docker`镜像运行带有`my_custom_label`标签的Job。
 - `my_custom_label:host`：在主机上直接运行带有`my_custom_label`标签的Job。
 - `my_custom_label`：等同于`my_custom_label:host`。
- `my_custom_label:vm:ubuntu-latest`：（仅为示例，未实现）使用带有`ubuntu-latest` ISO的虚拟机运行带有`my_custom_label`标签的Job。

 ## 通信协议

-由于act runner是Gitea的独立部分，我们需要一种协议让Runner与Gitea实例进行通信。
+由于 runner 是 Gitea 的独立部分，我们需要一种协议让 Runner 与 Gitea 实例进行通信。
 然而，我们不认为让Gitea监听一个新端口是个好主意。
 相反，我们希望重用HTTP端口，这意味着我们需要一个与HTTP兼容的协议。
 因此，我们选择使用基于HTTP的gRPC。

-我们使用[actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 进行连接。
+该协议定义在[actions-proto-def](https://gitea.com/gitea/actions-proto-def)中，其Go代码位于[actionslib](https://gitea.com/gitea/actionslib)。
 有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。

 ## 网络架构

 让我们来看一下整体的网络架构。
-这将帮助您解决一些问题，并解释为什么使用回环地址注册Runner是个不好的主意。
+这将帮助您解决一些问题，并解释为什么使用回环地址注册 Runner 是个不好的主意。

 ![network](/images/usage/actions/network.png)

 图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。

-### 连接 1，act runner到Gitea实例
+### 连接 1，runner 到 Gitea 实例

-act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
+Runner 必须能够连接到Gitea以接收任务并发送执行结果回来。

-### 连接 2，Job容器到Gitea实例
+### 连接 2，Job 容器到 Gitea 实例

 即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。
 举个例子，如果工作流中包含 `actions/checkout@v4`，Job容器需要连接到Gitea来获取代码。
@@ -93,11 +68,11 @@ act runner 必须能够连接到Gitea以接收任务并发送执行结果回来
 如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。
 然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。

-### 连接 3，act runner到互联网
+### 连接 3，runner 到互联网

-当您使用诸如 `actions/checkout@v4` 的一些Actions时，act runner下载的是脚本，而不是Job容器。
-默认情况下，它从[github.com](http://github.com/)下载，因此需要访问互联网。如果您设置的是 self，
-那么默认将从您的当前Gitea实例下载，那么此步骤不需要连接到互联网。
+当您使用诸如 `actions/checkout@v4` 的一些Actions时， runner下载的是脚本，而不是Job容器。
+默认情况下，它从[github.com](https://github.com/)下载这些脚本，这需要访问互联网。
+如果将`DEFAULT_ACTIONS_URL`设置为`self`，或使用`uses: self:owner/repo@ref`，它会改为从您的Gitea实例下载。
 它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。

 然而，互联网访问并不是绝对必需的。
@@ -27,34 +27,19 @@ DEFAULT_REPO_UNITS = ...,repo.actions

 ## 使用`actions/checkout@v4`等Actions时，Job容器会从何处下载脚本？

-GitHub 上有成千上万个 [Actions 脚本](https://github.com/marketplace?type=actions)。
-当您编写 `uses: actions/checkout@v4` 时，它默认会从 [github.com/actions/checkout](https://github.com/actions/checkout) 下载脚本。
-那如果您想使用一些托管在其它平台上的脚本呢，比如在 gitea.com 上的？
+默认从`https://github.com`下载，当`[actions].DEFAULT_ACTIONS_URL`为`self`时则从您自己的实例下载，参见[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。

-好消息是，您可以指定要从任何位置使用Actions的URL前缀。
-这是Gitea Actions中的额外语法。
-例如：
+要使用其他位置的Action，请指明其主机：

- `uses: https://gitea.com/xxx/xxx@xxx`
- `uses: https://github.com/xxx/xxx@xxx`
- `uses: http://your_gitea_instance.com/xxx@xxx`
-
-注意，`https://`或`http://`前缀是必需的！
-
-这是与 GitHub Actions 的一个区别，GitHub Actions 只允许使用托管在 GitHub 上的 actions 脚本。
-但用户理应拥有权利去灵活决定如何运行 Actions。
-
-另外，如果您希望您的 Runner 默认从您自己的 Gitea 实例下载 Actions，可以通过设置 `[actions].DEFAULT_ACTIONS_URL`进行配置。
-参见[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
+- `uses: https://gitea.com/owner/repo@ref`
+- `uses: http://your_gitea_instance.com/owner/repo@ref`
+- `uses: self:owner/repo@ref`，用于您自己的Gitea实例

 ## 如何限制Runner的权限？

-Runner仅具有连接到您的Gitea实例的权限。
-当任何Runner接收到要运行的Job时，它将临时获得与Job关联的仓库的有限权限。
-如果您想为Runner提供更多权限，允许它访问更多私有仓库或外部系统，您可以向其传递[密钥](usage/actions/secrets.md)。
-
-对于 Actions 的细粒度权限控制是一项复杂的工作。
-在未来，我们将添加更多选项以使Gitea更可配置，例如允许对仓库进行更多写访问或对同一组织中的所有仓库进行读访问。
+Runner仅连接到您的Gitea实例。
+对于每个Job，Runner会获得一个仅限于该Job所属仓库的`GITEA_TOKEN`，参见[Actions Job令牌权限](token-permissions.md)。
+如需让Job访问更多私有仓库或外部系统，请向其传递[密钥](usage/actions/secrets.md)。

 ## 如何避免被黑客攻击？

@@ -73,21 +58,10 @@ Runner仅具有连接到您的Gitea实例的权限。
 - 对于 fork 的拉取请求，需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
 - 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner，我们不会反对，只是不会在我们的组织中使用它。然而，他们应该注意确保该Runner不被他们不认识的其他用户使用。

-## act runner支持哪些操作系统？
+## Runner 支持哪些操作系统？

-它在Linux、macOS和Windows上运行良好。
-虽然理论上支持其他操作系统，但需要进一步测试。
-
-需要注意的一点是，如果选择直接在主机上运行Job而不是在Job容器中运行，操作系统之间的环境差异可能会导致意外的失败。
-
-例如，在大多数情况下，Windows上没有可用的bash，而act尝试默认使用bash运行脚本。
-因此，您需要在工作流文件中将默认shell指定为`powershell`，参考[defaults.run](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun)。
-
-```yaml
-defaults:
-  run:
-    shell: powershell
-```
+官方发布了Linux、macOS和Windows的二进制文件。
+理论上，Go和Docker支持的其他系统也可以运行。

 ## 为什么选择GitHub Actions？为什么不选择与GitLab CI/CD兼容的工具？

@@ -99,49 +73,20 @@ defaults:

 ## 如果它在多个标签上运行，例如 `runs-on: [label_a, label_b]`，会发生什么？

-这是有效的语法。
-它意味着它应该在具有`label_a` **和** `label_b`标签的Runner上运行，参考[GitHub Actions的工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
-不幸的是，act runner 并不支持这种方式。
-如上所述，我们将标签映射到环境：
-
- `ubuntu` → `ubuntu:22.04`
- `centos` → `centos:8`
-
-但我们需要将标签组映射到环境，例如：
-
- `[ubuntu]` → `ubuntu:22.04`
- `[with-gpu]` → `linux:with-gpu`
- `[ubuntu, with-gpu]` → `ubuntu:22.04_with-gpu`
-
-我们还需要重新设计任务分配给Runner的方式。
-具有`ubuntu`、`centos`或`with-gpu`的Runner并不一定表示它可以接受`[centos, with-gpu]`的Job。
-因此，Runner应该通知Gitea实例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]`的Job。
-这不是一个技术问题，只是在早期设计中被忽视了。
-参见[runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
-
-目前，act runner尝试匹配标签中的每一个，并使用找到的第一个匹配项。
+该Job会在拥有所有这些标签的Runner上运行，与[GitHub](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)一致。
+Runner会使用这些标签中它所拥有的第一个标签对应的环境。

 ## 代理标签和自定义标签对于Runner有什么区别？

-![labels](/images/usage/actions/labels.png)
-
-代理标签是由Runner在注册过程中向Gitea实例报告的。
-而自定义标签则是由Gitea的管理员或组织或仓库的所有者手动添加的（取决于Runner所属的级别）。
-
-然而，目前这方面的设计还有待改进，因为它目前存在一些不完善之处。
-您可以向已注册的Runner添加自定义标签，比如 `centos`，这意味着该Runner将接收具有`runs-on: centos`的Job。
-然而，Runner可能不知道要使用哪个环境来执行该标签，导致它使用默认镜像或导致逻辑死胡同。
-这个默认值可能与用户的期望不符。
-参见[runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
-
-与此同时，如果您想更改Runner的标签，我们建议您重新注册Runner。
+Gitea已不再有自定义标签。
+Runner每次启动时都会声明其标签，标签来自`runner.labels`配置或注册时指定的标签，因此请在那里修改并重启Runner。

 ## Gitea Actions runner会有更多的实现吗？

-虽然我们希望提供更多的选择，但由于我们有限的人力资源，act runner将是唯一受支持的官方Runner。
-然而，无论您如何决定，Gitea 和act runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
+虽然我们希望提供更多的选择，但由于我们有限的人力资源，runner 将是唯一受支持的官方 Runner。
+然而，无论您如何决定，Gitea 和 runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
 我们支持您的选择，无论您如何决定。
-如果您选择分支act runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
+如果您选择分支 runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。

 ## Gitea 支持哪些工作流触发事件？

@@ -165,3 +110,11 @@ defaults:

 > 对于 `pull_request` 事件，在 [GitHub Actions](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) 中 `ref` 是 `refs/pull/:prNumber/merge`，它指向这个拉取请求合并提交的一个预览。但是 Gitea 没有这种 reference。
 > 因此，Gitea Actions 中 `ref` 是 `refs/pull/:prNumber/head`，它指向这个拉取请求的头分支而不是合并提交的预览。
+
+## 如何共享私有仓库中的Actions和可复用工作流？
+
+前往仓库的**设置** > **Actions** > **常规**页面并添加协作所有者。
+协作所有者的私有仓库可以访问当前仓库中的Actions和工作流。
+
+如需在同一用户或组织内共享，请改为在该用户或组织的**设置** > **Actions** > **常规** > **跨仓库访问**中添加这些私有仓库。
+参见[跨仓库访问](token-permissions.md#cross-repository-access)。
@@ -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`按仓库计数，而不是按工作流计数。
@@ -21,8 +21,8 @@ Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且
 ## Runner

 和其他CI/CD解决方案一样，Gitea不会自己运行Job，而是将Job委托给Runner。
-Gitea Actions的Runner被称为[act runner](https://gitea.com/gitea/act_runner)，它是一个独立的程序，也是用Go语言编写的。
-它是基于[nektos/act](http://github.com/nektos/act)的一个[分支](https://gitea.com/gitea/act) 。
+Gitea Actions的Runner被称为[Gitea Runner](https://gitea.com/gitea/runner)，它是一个独立的程序，也是用Go语言编写的。
+它的重要部分来自[nektos/act](http://github.com/nektos/act)的一个硬分支。

 由于Runner是独立部署的，可能存在潜在的安全问题。
 为了避免这些问题，请遵循两个简单的规则：
@@ -25,10 +25,10 @@ ENABLED=true

 ### 设置Runner

-Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
+Gitea Actions需要[runner](https://gitea.com/gitea/runner) 来运行Job。
 为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。

-您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
+您可以使用[预构建的二进制文件](http://dl.gitea.com/gitea-runner)或[容器镜像](https://hub.docker.com/r/gitea/runner/tags)来设置Runner。

 在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
 如果出现问题，这样调试起来会更容易。
@@ -40,7 +40,7 @@ Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job
 在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：

 ```bash
-./act_runner register --no-interactive --instance <instance> --token <token>
+gitea-runner register --no-interactive --instance <instance> --token <token>
 ```

 需要两个必需的参数：`instance` 和 `token`。
@@ -52,10 +52,10 @@ Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
 如果不确定使用哪个地址，通常选择局域网地址即可。

 `token` 用于身份验证和标识，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。
-它只能使用一次，并且不能用于注册多个Runner。
+每个令牌都可用于注册多个Runner。通过重置链接替换为新令牌后，旧令牌将失效。
 您可以从以下位置获取不同级别的`token`,从而创建出相应级别的`runner`

- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/actions/runners`。
+- 实例级别：管理员设置页面，例如 `<your_gitea.com>/-/admin/actions/runners`。
 - 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
 - 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。

@@ -68,14 +68,14 @@ Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
 最后，是时候启动Runner了：

 ```bash
-./act_runner daemon
+gitea-runner daemon
 ```

 您可以在管理页面上看到新的Runner：

 ![view runner](/images/usage/actions/view-runner.png)

-您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
+您可以通过访问[Gitea Runner](runner) 获取更多信息。

 ### 使用Actions

@@ -0,0 +1,57 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "runner"
+sidebar_position: 20
+aliases:
+  - /zh-cn/act-runner
+---
+
+# Runner
+
+本页面将介绍[Gitea Runner](https://gitea.com/gitea/runner)，这是Gitea Actions的Runner。
+
+:::tip
+详细的安装、配置和使用说明，请参阅 [Gitea Runner 文档](/runner/)。
+:::
+
+## 获取注册令牌
+
+### Runner级别
+
+您可以在不同级别上注册Runner，它可以是：
+
+- 实例级别：Runner将为实例中的所有存储库运行Job。
+- 组织级别：Runner将为组织中的所有存储库运行Job。
+- 存储库级别：Runner将为其所属的存储库运行Job。
+
+请注意，即使存储库具有自己的存储库级别Runner，它仍然可以使用实例级别或组织级别Runner。未来的版本可能提供更多对此进行更好控制的选项。
+
+Runner级别决定了从哪里获取注册令牌。
+
+- 实例级别：管理员设置页面，例如 `<your_gitea.com>/-/admin/actions/runners`。
+- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
+- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
+
+如果您无法看到设置页面，请确保您具有正确的权限并且已启用 Actions。
+
+注册令牌的格式是一个随机字符串 `D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx`。
+
+注册令牌也可以通过 Gitea 的 [命令行](../../administration/command-line.md#actions-generate-runner-token) 获得:
+
+```
+gitea --config /etc/gitea/app.ini actions generate-runner-token
+```
+
+用户也可以使用 `GITEA_RUNNER_REGISTRATION_TOKEN` 或 `GITEA_RUNNER_REGISTRATION_TOKEN_FILE` 环境变量以在 Gitea 启动时设置全局的注册令牌，例如：
+
+```
+openssl rand -hex 24 > /some-dir/runner-token
+export GITEA_RUNNER_REGISTRATION_TOKEN_FILE=/some-dir/runner-token
+./gitea --config ...
+```
+
+来自环境变量的令牌在通过 Web 界面或 API 重置(重新创建新令牌)前将一直有效。
+
+令牌可用于注册多个 Runner，直到使用 Web 界面中的令牌重置链接将其撤销并替换为新令牌。
+
+获取注册令牌后，请参阅 [Gitea Runner 文档](/runner/) 了解如何安装、配置和运行您的 Runner。
@@ -0,0 +1,119 @@
+---
+date: "2026-06-26T00:00:00+00:00"
+slug: "scoped-workflows"
+sidebar_position: 60
+---
+
+# 作用域工作流
+
+作用域工作流（Scoped Workflows）让你把 Actions 工作流集中维护在一个**源（source）**仓库中，并让它们自动在许多其他仓库上运行，而无需把工作流文件复制到每个仓库里。
+
+提交到源仓库作用域工作流目录下的工作流文件，会在该源所适用的每个仓库（称为**消费方（consuming）**仓库）上运行。每次运行都在**消费方仓库自身的上下文**中执行：使用它的 runner、密钥、`GITEA_TOKEN` 和分支，而工作流**内容则读取自源仓库**。这适用于在组织或实例范围内强制推行共享 CI：代码检查、安全扫描、合规或策略检查等。
+
+## 级别
+
+源仓库可以在两个级别注册：
+
+- **所有者级别（Owner level）**：由组织或用户注册。该源的工作流会在该组织或用户拥有的每个仓库上运行。
+- **实例级别（Instance level）**：由站点管理员注册。该源的工作流会在实例上的**每一个**仓库上运行。
+
+同一个仓库可以同时在两个级别注册；对于每个匹配的事件，它仍只会被评估一次。
+
+:::note
+实例级别的源适用于实例上的**每一个**仓库，且被设为必需（required）的源无法被选择退出（opt out）。检测会在每个仓库的每次事件上运行。请谨慎注册。
+:::
+
+## 配置
+
+作用域工作流存放在一个与常规工作流分开的目录中，由 `app.ini` 中 `[actions]` 段的 `SCOPED_WORKFLOW_DIRS` 控制：
+
+```ini
+[actions]
+SCOPED_WORKFLOW_DIRS = .gitea/scoped_workflows
+```
+
+- 默认值为 `.gitea/scoped_workflows`。
+- 可以列出多个目录（以逗号分隔）。
+- **不得与** `WORKFLOW_DIRS`（常规工作流目录，默认为 `.gitea/workflows` 和 `.github/workflows`）**重叠**。
+- 留空意味着没有任何目录存放作用域工作流，因此不会找到也不会运行任何作用域工作流。设置页面仍会显示、源仍可注册，但不会有任何作用域工作流运行。
+
+把作用域工作流放在它们自己的目录中，意味着源仓库**自身**的 Actions 不受影响：只有 `SCOPED_WORKFLOW_DIRS` 下的文件才会被当作作用域工作流。
+
+## 从一个仓库提供作用域工作流
+
+1. 在准备作为源的仓库中，把工作流文件提交到其**默认分支**上的作用域工作流目录下，例如 `.gitea/scoped_workflows/lint.yaml`：
+
+   ```yaml
+   name: Lint
+   on: [push, pull_request]
+   jobs:
+     lint:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+         - run: echo "lint the consuming repository here"
+   ```
+
+2. 将该仓库注册为源：
+
+   - **组织**：*组织设置 -> Actions -> 作用域工作流*
+   - **用户**：*用户设置 -> Actions -> 作用域工作流*
+   - **实例（管理员）**：*管理后台 -> Actions -> 作用域工作流*
+
+   搜索并添加该仓库。此后，它的作用域工作流便会适用于该级别下的消费方仓库。
+
+源仓库也在它自己的作用域内，因此它会像其他消费方一样在自身上运行这些工作流。
+
+## 作用域工作流如何运行
+
+- 该运行属于**消费方**仓库，使用它的 runner、密钥、`GITEA_TOKEN` 和 ref。它在那里的表现与普通运行一致，包括重跑、日志和提交状态。
+- 工作流**内容读取自源**仓库，并钉定在事件发生时源默认分支的 commit 上。
+- 检测使用消费方仓库的事件，因此工作流的 `on:` 触发器（例如 `push` 和 `pull_request`）必须与该事件匹配。
+
+## 选择退出（Opting out）
+
+消费方仓库可以在其 **Actions** 页面（该工作流会显示在其源之下）禁用一个它不想要的作用域工作流。已被标记为**必需（required）**（见下文）的工作流，消费方仓库永远无法将其禁用，也无法选择退出。
+
+## 必需工作流与合并门禁
+
+在作用域工作流设置页面上，你可以把单个工作流标记为**必需（required）**，并为每个工作流给定一个或多个**状态检查模式（status-check patterns）**（每行一个 glob）。一个必需的作用域工作流：
+
+- 无法被消费方仓库禁用。
+- 会对合并请求（PR）形成合并门禁：消费方的 PR 只有在一个匹配**每一个**模式的提交状态都**通过**后才能合并（必须存在且通过，must-present-and-pass）。一个从不产生任何状态的必需检查会**阻止**合并，而不是被静默跳过，因此在消费方关闭 Actions 也无法绕过它。
+
+作用域运行产生的状态检查 context 形如：
+
+```
+<源仓库全名>: <工作流显示名> / <job> (<event>)
+```
+
+设置页面会为每个工作流预览这些 “Expected status checks（预期状态检查）”，并标记出与你的模式匹配的项，便于你确认模式是否正确。一种常见模式是对 job 和 event 使用通配符，例如 `my-org/ci-repo: Lint / *`。
+
+强制范围：
+
+- 必需检查会在任何设有**分支保护规则**的目标分支上强制生效，即使该规则自身的状态检查处于关闭状态。
+- **没有**保护规则的目标分支不受门禁约束。
+
+:::warning
+只有运行在会产生提交状态的事件（`push`、`pull_request`、`pull_request_target`、`release`）上的工作流才能被设为必需。仅运行在 `workflow_dispatch`、`schedule` 或 `workflow_call` 等事件上的工作流不会产生任何状态，因此把它设为必需会**永久**阻止每一个消费方 PR 的合并。设置页面在这种情况下会向你发出警告。
+:::
+
+## 可复用工作流（`uses:`）
+
+作用域工作流可以调用可复用工作流：
+
+- **本地**引用（`uses: ./...` 或 `uses: $/...`）会相对于**源**仓库解析：即调用方工作流内容的来源仓库，而非消费方仓库。
+- **跨仓库**引用（`uses: owner/repo/...@ref` 或 `uses: self:owner/repo/...@ref`）会以**消费方仓库的**读取权限来解析。如果它指向一个私有仓库，请确保每个消费方仓库都能读取它，否则工作流会在那里失败。
+
+可复用工作流可以放在源仓库的 `SCOPED_WORKFLOW_DIRS`（或 `WORKFLOW_DIRS`）之下。
+
+## 安全注意事项
+
+源仓库的工作流内容会在它所适用的每个仓库中执行，其步骤脚本及其输出会写入该仓库的 Actions 日志，任何能查看消费方仓库 Actions 的人都能读取这些日志。
+
+- 因此，将一个**私有**仓库注册为源，会通过这些日志泄露其工作流逻辑。只应注册那些其工作流内容可以与每个消费方仓库共享的仓库。
+
+## 限制
+
+- 目前不支持将 `on: schedule` 和 `on: workflow_run` 作为作用域工作流触发器。
+- 作用域工作流内容读取自源的默认分支；源的其他分支不会被使用。
@@ -0,0 +1,130 @@
+---
+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`（如果目标功能支持）
+- `id-token`（`write`允许请求[OpenID Connect令牌](openid-connect.md)，`read`不授予任何权限）
+
+如果同时指定了`contents`和更细粒度的权限范围（如`code`或`releases`），则该单元以更细粒度的权限范围为准。
+
+<a id="compatibility-notes"></a>
+### 兼容性说明
+
+Gitea支持GitHub Actions权限范围的一个子集。
+Gitea Actions目前不支持`statuses`、`checks`、`deployments`、`security-events`和`pages`等GitHub专有的权限范围。
+
+Gitea还提供了一些仓库单元权限范围，它们在GitHub Actions中不作为独立的权限范围存在：
+
+- `code`
+- `releases`
+- `wiki`
+- `projects`
+
+<a id="default-permission-mode"></a>
+## 默认权限模式
+
+如果工作流和Job都没有定义`permissions:`，Gitea会使用所配置的默认模式：
+
+- **宽松**：对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>
+## 配置位置
+
+您可以在以下位置配置默认权限和最大权限：
+
+- **用户/组织**：`Settings` → `Actions` → `General`
+- **仓库**：`Settings` → `Actions` → `General`
+  - 对于组织中的仓库，可以遵循所有者级别的配置，也可以通过**覆盖所有者级别的配置**选择不遵循。
+
+注意：仅在启用**仓库Actions**后，才会显示仓库级别的令牌权限设置。
+
+<a id="fork-pull-requests"></a>
+## Fork拉取请求
+
+出于安全考虑，由fork拉取请求触发的工作流始终只拥有仓库内容的只读权限，与工作流的`permissions:`或设置无关。这些Job也无法获取OpenID Connect令牌。
+
+<a id="cross-repository-access"></a>
+## 跨仓库访问
+
+默认情况下，`GITEA_TOKEN`只能访问：
+
+- Job所属仓库（依据计算出的权限）
+- 公开仓库（只读）
+
+默认拒绝访问其他私有仓库。
+用户或组织可以通过**设置 → Actions → 常规 → 跨仓库访问**，允许以只读方式访问选定的私有仓库。
+
+私有仓库也可以通过**设置 → Actions → 常规**允许选定的协作所有者。
+这样，这些所有者的私有仓库便可读取当前私有仓库以供Actions使用，例如私有Actions和可复用工作流。
+
+fork拉取请求的工作流永远不会获得对私有仓库的跨仓库访问权限，即使这些仓库已被列出。
@@ -57,4 +57,4 @@ WORK_IN_PROGRESS_PREFIXES=WIP:,[WIP]

 ## 合并请求模板

-有关合并请求模板的更多信息请您移步 : [工单与合并请求模板](usage/issue-pull-request-templates.md)
+有关合并请求模板的更多信息请您移步 : [工单与合并请求模板](issue-pull-request-templates.md)