完成文档部分内容

2025-07-29 20:56:05 +08:00
parent 1e3e4d18ae
commit 81217e1e64
68 changed files with 6384 additions and 71 deletions
--- a/docs/document/usage/actions/act-runner.md
+++ b/docs/document/usage/actions/act-runner.md
@@ -0,0 +1,267 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "act-runner"
+sidebar_position: 20
+---
+
+# Act Runner
+
+本页面将详细介绍[Act Runner](https://gitea.com/gitea/act_runner)，这是Gitea Actions的Runner。
+
+## 要求
+
+建议在Docker容器中运行Job，因此您需要首先安装Docker。
+并确保Docker守护进程正在运行。
+
+其他与Docker API兼容的OCI容器引擎也应该可以正常工作，但尚未经过测试。
+
+但是，如果您确定要直接在主机上运行Job，则不需要Docker。
+
+## 安装
+
+有多种安装Act Runner的方法。
+
+### 下载二进制文件
+
+您可以从[发布页面](https://gitea.com/gitea/act_runner/releases)下载二进制文件。
+然而，如果您想使用最新的夜间构建版本，可以从[下载页面](https://dl.gitea.com/act_runner/)下载。
+
+下载二进制文件时，请确保您已经下载了适用于您的平台的正确版本。
+您可以通过运行以下命令进行检查：
+
+```bash
+chmod +x act_runner
+./act_runner --version
+```
+
+如果看到版本信息，则表示您已经下载了正确的二进制文件。
+
+### 使用 Docker 镜像
+
+您可以使用[docker hub](https://hub.docker.com/r/gitea/act_runner/tags)上的Docker镜像。
+与二进制文件类似，您可以使用`nightly`标签使用最新的夜间构建版本，而`latest`标签是最新的稳定版本。
+
+```bash
+docker pull docker.io/gitea/act_runner:latest # for the latest stable release
+docker pull docker.io/gitea/act_runner:nightly # for the latest nightly build
+```
+
+## 配置
+
+配置通过配置文件进行。它是可选的，当没有指定配置文件时，将使用默认配置。
+
+您可以通过运行以下命令生成配置文件：
+
+```bash
+./act_runner generate-config
+```
+
+默认配置是安全的，可以直接使用。
+
+```bash
+./act_runner generate-config > config.yaml
+./act_runner --config config.yaml [command]
+```
+
+您亦可以如下使用 docker 创建配置文件：
+
+```bash
+docker run --entrypoint="" --rm -it docker.io/gitea/act_runner:latest act_runner generate-config > config.yaml
+```
+
+当使用Docker镜像时，可以使用`CONFIG_FILE`环境变量指定配置文件。确保将文件作为卷挂载到容器中：
+
+```bash
+docker run -v $(pwd)/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...
+```
+
+您可能注意到上面的命令都是不完整的，因为现在还不是运行Act Runner的时候。
+在运行Act Runner之前，我们需要首先将其注册到您的Gitea实例中。
+
+## 注册
+
+在运行Act Runner之前，需要进行注册，因为Runner需要知道从哪里获取Job，并且对于Gitea实例来说，识别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 界面中的令牌重置链接将其撤销并替换为新令牌。
+
+### 注册Runner
+
+可以通过运行以下命令来注册Act Runner：
+
+```bash
+./act_runner register
+```
+
+或者，您可以使用 `--config` 选项来指定前面部分提到的配置文件。
+
+```bash
+./act_runner --config config.yaml register
+```
+
+您将逐步输入注册信息，包括：
+
+- Gitea 实例的 URL，例如 `https://gitea.com/` 或 `http://192.168.8.8:3000/`。
+- 注册令牌。
+- Runner名称（可选）。如果留空，将使用主机名。
+- Runner标签（可选）。如果留空，将使用默认标签。
+
+您可能对Runner标签感到困惑，稍后将对其进行解释。
+
+如果您想以非交互方式注册Runner，可以使用参数执行以下操作。
+
+```bash
+./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
+```
+
+注册Runner后，您可以在当前目录中找到一个名为 `.runner` 的新文件。该文件存储注册信息。
+请不要手动编辑该文件。
+如果此文件丢失或损坏，可以直接删除它并重新注册。
+
+如果您想将注册信息存储在其他位置，请在配置文件中指定，并不要忘记指定 `--config` 选项。
+
+### 使用Docker注册Runner
+
+如果您使用的是Docker镜像，注册行为会略有不同。在这种情况下，注册和运行合并为一步，因此您需要在运行Act Runner时指定注册信息。
+
+```bash
+docker run \
+    -v $(pwd)/config.yaml:/config.yaml \
+    -v $(pwd)/data:/data \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    -e CONFIG_FILE=/config.yaml \
+    -e GITEA_INSTANCE_URL=<instance_url> \
+    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
+    -e GITEA_RUNNER_NAME=<runner_name> \
+    -e GITEA_RUNNER_LABELS=<runner_labels> \
+    --name my_runner \
+    -d gitea/act_runner:nightly
+```
+
+您可能注意到我们已将`/var/run/docker.sock`挂载到容器中。
+这是因为Act Runner将在Docker容器中运行Job，因此它需要与Docker守护进程进行通信。
+如前所述，如果要在主机上直接运行Job，可以将其移除。
+需要明确的是，这里的 "主机" 实际上指的是当前运行 Act Runner的容器，而不是主机机器本身。
+
+### 使用 Docker compose 运行 Runner
+
+您亦可使用如下的 `docker-compose.yml`:
+
+```yml
+version: "3.8"
+services:
+  runner:
+    image: gitea/act_runner:nightly
+    environment:
+      CONFIG_FILE: /config.yaml
+      GITEA_INSTANCE_URL: "${INSTANCE_URL}"
+      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
+      GITEA_RUNNER_NAME: "${RUNNER_NAME}"
+      GITEA_RUNNER_LABELS: "${RUNNER_LABELS}"
+    volumes:
+      - ./config.yaml:/config.yaml
+      - ./data:/data
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+### 当您使用 Docker 镜像启动 Runner，如何配置 Cache
+
+如果你不打算在工作流中使用 `actions/cache`，你可以忽略本段。
+
+如果您在使用 `actions/cache` 时没有进行额外的配置，将会返回以下错误信息：
+> Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
+
+这个错误的原因是 runner 容器和作业容器位于不同的网络中，因此作业容器无法访问 runner 容器。
+因此，配置 cache 动作以确保其正常运行是非常重要的。请按照以下步骤操作：
+
+- 1.获取 Runner 容器所在主机的 LAN（本地局域网） IP 地址。
+- 2.获取一个 Runner 容器所在主机的空闲端口号。
+- 3.在配置文件中如下配置：
+
+```yaml
+cache:
+  enabled: true
+  dir: ""
+  # 使用步骤 1. 获取的 LAN IP
+  host: "192.168.8.17"
+  # 使用步骤 2. 获取的端口号
+  port: 8088
+```
+
+- 4.启动容器时, 将 Cache 端口映射至主机。
+
+```bash
+docker run \
+  --name gitea-docker-runner \
+  -p 8088:8088 \
+  -d gitea/act_runner:nightly
+```
+
+### 标签
+
+Runner的标签用于确定Runner可以运行哪些Job以及如何运行它们。
+
+默认标签为`ubuntu-latest:docker://node:16-bullseye,ubuntu-22.04:docker://node:16-bullseye,ubuntu-20.04:docker://node:16-bullseye,ubuntu-18.04:docker://node:16-buster`。
+它们是逗号分隔的列表，每个项目都是一个标签。
+
+让我们以 `ubuntu-22.04:docker://node:16-bullseye` 为例。
+它意味着Runner可以运行带有`runs-on: ubuntu-22.04`的Job，并且该Job将在使用`node:16-bullseye`镜像的Docker容器中运行。
+
+如果默认镜像无法满足您的需求，并且您有足够的磁盘空间可以使用更好、更大的镜像，您可以将其更改为`ubuntu-22.04:docker://<您喜欢的镜像>`。
+您可以在[act 镜像](https://github.com/nektos/act/blob/master/IMAGES.md)上找到更多有用的镜像。
+
+如果您想直接在主机上运行Job，您可以将其更改为`ubuntu-22.04:host`或仅`ubuntu-22.04`，`:host`是可选的。
+然而，我们建议您使用类似`linux_amd64:host`或`windows:host`的特殊名称，以避免误用。
+
+从 Gitea 1.21 开始，您可以通过修改 runner 的配置文件中的 `container.labels` 来更改标签（如果没有配置文件，请参考 [配置教程](#配置)），通过执行 `./act_runner daemon --config config.yaml` 命令重启 runner 之后，这些新定义的标签就会生效。
+
+## 运行
+
+注册完Runner后，您可以通过运行以下命令来运行它：
+
+```bash
+./act_runner daemon
+# or
+./act_runner daemon --config config.yaml
+```
+
+Runner将从Gitea实例获取Job并自动运行它们。
+
+由于Act Runner仍处于开发中，建议定期检查最新版本并进行升级。
--- a/docs/document/usage/actions/badge.md
+++ b/docs/document/usage/actions/badge.md
@@ -0,0 +1,27 @@
+---
+date: "2023-02-25T00:00:00+00:00"
+slug: "badge"
+sidebar_position: 110
+---
+
+# Badge
+
+Gitea has its builtin Badge system which allows you to display the status of your repository in other places. You can use the following badges:
+
+## Workflow Badge
+
+The Gitea Actions workflow badge is a badge that shows the status of the latest workflow run.
+It is designed to be compatible with [GitHub Actions workflow badge](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge).
+
+You can use the following URL to get the badge:
+
+```
+https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}/badge.svg?branch={branch}&event={event}&style={style}
+```
+
+- `{owner}`: The owner of the repository.
+- `{repo}`: The name of the repository.
+- `{workflow_file}`: The name of the workflow file.
+- `{branch}`: Optional. The branch of the workflow. Default to your repository's default branch.
+- `{event}`: Optional. The event of the workflow. Default to none.
+- `{style}`: Optional. Style of the badge, either `flat` or `flat-square`. Default to `flat`.
--- a/docs/document/usage/actions/comparison.md
+++ b/docs/document/usage/actions/comparison.md
@@ -0,0 +1,125 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "comparison"
+sidebar_position: 15
+---
+
+# 与GitHub Actions的对比
+
+尽管Gitea Actions旨在与GitHub Actions兼容，但它们之间存在一些差异。
+
+## 额外功能
+
+### Action URL绝对路径
+
+Gitea Actions支持通过URL绝对路径定义actions，这意味着您可以使用来自任何Git存储库的Actions。
+例如，`uses: https://github.com/actions/checkout@v4`或`uses: http://your_gitea.com/owner/repo@branch`。
+
+### 使用Go编写Actions
+
+Gitea Actions支持使用Go编写Actions。
+请参阅[创建Go Actions](https://blog.gitea.com/creating-go-actions/)。
+
+### 支持非标准的调度语法 @yearly, @monthly, @weekly, @daily, @hourly
+
+Github Actions 不支持这些语法，详见： https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
+
+## 不支持的工作流语法
+
+### `concurrency`
+
+这是用于一次运行一个Job。
+请参阅[使用并发](https://docs.github.com/zh/actions/using-jobs/using-concurrency)。
+
+Gitea Actions目前不支持此功能。
+
+### `run-name`
+
+这是工作流生成的工作流运行的名称。
+请参阅[GitHub Actions 的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。
+
+Gitea Actions目前不支持此功能。
+
+### `permissions`和`jobs.<job_id>.permissions`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。
+
+Gitea Actions目前不支持此功能。
+
+### `jobs.<job_id>.timeout-minutes`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes)。
+
+Gitea Actions目前不支持此功能。
+
+### `jobs.<job_id>.continue-on-error`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。
+
+Gitea Actions目前不支持此功能。
+
+### `jobs.<job_id>.environment`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。
+
+Gitea Actions 目前不支持此功能。
+
+### 复杂的`runs-on`
+
+请参阅[GitHub Actions的工作流语法](https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
+
+Gitea Actions目前只支持`runs-on: xyz`或`runs-on: [xyz]`。
+
+### `hashFiles`表达式
+
+请参阅[表达式](https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles)。
+
+Gitea Actions目前不支持此功能，如果使用它，结果将始终为空字符串。
+
+作为解决方法，您可以使用[go-hashfiles](https://gitea.com/actions/go-hashfiles)。
+
+## 缺失的功能
+
+### 问题匹配器
+
+问题匹配器是一种扫描Actions输出以查找指定正则表达式模式并在用户界面中突出显示该信息的方法。
+请参阅[问题匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。
+
+Gitea Actions目前不支持此功能。
+
+### 为错误创建注释
+
+请参阅[为错误创建注释](https://docs.github.com/zh/actions/using-workflows/workflow-commands-for-github-actions#example-creating-an-annotation-for-an-error)。
+
+Gitea Actions目前不支持此功能。
+
+### 表达式
+
+对于 [表达式](https://docs.github.com/en/actions/learn-github-actions/expressions), 当前仅 [`always()`](https://docs.github.com/en/actions/learn-github-actions/expressions#always) 被支持。
+
+## 缺失的UI功能
+
+### 预处理和后处理步骤
+
+预处理和后处理步骤在Job日志用户界面中没有自己的用户界面。
+
+### 服务步骤
+
+服务步骤在Job日志用户界面中没有自己的用户界面。
+
+## 不一样的行为
+
+### 下载Actions
+
+当 `[actions].DEFAULT_ACTIONS_URL` 保持默认值为 `github` 时，Gitea将会从 https://github.com 下载相对路径的actions。比如：
+如果你使用 `uses: actions/checkout@v4`，Gitea将会从 https://github.com/actions/checkout.git 下载这个 actions 项目。
+如果你想要从另外一个 Git服务下载actions，你只需要使用绝对URL `uses: https://gitea.com/actions/checkout@v4` 来下载。
+
+如果你的 Gitea 实例是部署在一个互联网限制的网络中，也可以使用绝对地址来下载 actions。你也可以将配置项修改为 `[actions].DEFAULT_ACTIONS_URL = self`。这样所有的相对路径的actions引用，将不再会从 github.com 去下载，而会从这个 Gitea 实例自己的仓库中去下载。例如： `uses: actions/checkout@v4` 将会从 `[server].ROOT_URL`/actions/checkout.git 这个地址去下载 actions。
+
+设置`[actions].DEFAULT_ACTIONS_URL`进行配置。请参阅[配置备忘单](../../administration/config-cheat-sheet.md#actions-actions)。
+
+### 上下文可用性
+
+不检查上下文可用性，因此您可以在更多地方使用env上下文。
+请参阅[上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。
--- a/docs/document/usage/actions/design.md
+++ b/docs/document/usage/actions/design.md
@@ -0,0 +1,124 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "design"
+sidebar_position: 40
+---
+
+# Gitea Actions设计
+
+Gitea Actions由多个组件组成。本文档将对它们进行逐个描述。
+
+## Act
+
+[nektos/act](https://github.com/nektos/act) 项目是一个优秀的工具，允许你在本地运行GitHub Actions。
+我们受到了它的启发，并思考它是否可能为Gitea运行Actions。
+
+然而，尽管[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不同的服务器上运行。
+
+为了确保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`上运行的Job，并通过使用`centos:7`镜像的Docker容器来运行它。
+
+然而，Docker不是唯一的选择。
+act 也支持直接在主机上运行Job。
+这是通过像`linux_arm:host`这样的标签实现的。
+这个标签表示Runner可以接受需要在`linux_arm`上运行的Job，并直接在主机上运行它们。
+
+标签的设计遵循格式`label[:schema[:args]]`。
+如果省略了schema，则默认为`host`。
+
+因此，
+
+- `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实例进行通信。
+然而，我们不认为让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) 进行连接。
+有关 gRPC 的更多信息，请访问[其官方网站](https://grpc.io/)。
+
+## 网络架构
+
+让我们来看一下整体的网络架构。
+这将帮助您解决一些问题，并解释为什么使用回环地址注册Runner是个不好的主意。
+
+![network](../../../static/images/usage/actions/network.png)
+
+图片中标记了四个网络连接，并且箭头的方向表示建立连接的方向。
+
+### 连接 1，act runner到Gitea实例
+
+act runner 必须能够连接到Gitea以接收任务并发送执行结果回来。
+
+### 连接 2，Job容器到Gitea实例
+
+即使Job容器位于同一台机器上，它们的网络命名空间与Runner不同。
+举个例子，如果工作流中包含 `actions/checkout@v4`，Job容器需要连接到Gitea来获取代码。
+获取代码并不总是运行某些Job所必需的，但在大多数情况下是必需的。
+
+如果您使用回环地址注册Runner，当Runner与Gitea在同一台机器上时，Runner可以连接到Gitea。
+然而，如果Job容器尝试从本地主机获取代码，它将失败，因为Gitea不在同一个容器中。
+
+### 连接 3，act runner到互联网
+
+当您使用诸如 `actions/checkout@v4` 的一些Actions时，act runner下载的是脚本，而不是Job容器。
+默认情况下，它从[github.com](http://github.com/)下载，因此需要访问互联网。如果您设置的是 self，
+那么默认将从您的当前Gitea实例下载，那么此步骤不需要连接到互联网。
+它还默认从Docker Hub下载一些Docker镜像，这也需要互联网访问。
+
+然而，互联网访问并不是绝对必需的。
+您可以配置您的Gitea实例从您的内部网络设施中获取 Actions 或镜像。
+
+实际上，您的Gitea实例可以同时充当 Actions 市场和镜像注册表。
+您可以将GitHub上的Actions仓库镜像到您的Gitea实例，并将其用作普通Actions。
+而 [Gitea 容器注册表](usage/packages/container.md) 可用作Docker镜像注册表。
+
+### 连接 4，Job容器到互联网
+
+当使用诸如`actions/setup-go@v5`的Actions时，可能需要从互联网下载资源，以设置Job容器中的Go语言环境。
+因此，成功完成这些Actions需要访问互联网。
+
+然而，这也是可选的。
+您可以使用自定义的Actions来避免依赖互联网访问，或者可以使用已安装所有依赖项的打包的Docker镜像来运行Job。
+
+## 总结
+
+使用Gitea Actions只需要确保Runner能够连接到Gitea实例。
+互联网访问是可选的，但如果没有互联网访问，将需要额外的工作。
+换句话说：当Runner能够自行查询互联网时，它的工作效果最好，但您不需要将其暴露给互联网（无论是单向还是双向）。
+
+如果您在使用Gitea Actions时遇到任何网络问题，希望上面的图片能够帮助您进行故障排除。
--- a/docs/document/usage/actions/faq.md
+++ b/docs/document/usage/actions/faq.md
@@ -0,0 +1,167 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "faq"
+sidebar_position: 100
+---
+
+# Gitea Actions常见问题解答
+
+本页面包含一些关于Gitea Actions的常见问题和答案。
+
+## 是否可以在我的实例中默认禁用新仓库的Actions？
+
+是的，当您为实例启用Actions时，您可以选择默认启用actions单元以适用于所有新仓库。
+
+```ini
+[repository]
+; 去掉 repo.actions 将不会为新仓库自动启用actions
+DEFAULT_REPO_UNITS = ...,repo.actions
+```
+
+## 在工作流文件中应该使用`github.xyz`还是`gitea.xyz`？
+
+您可以使用`github.xyz`，Gitea将正常工作。
+如前所述，Gitea Actions的设计是与GitHub Actions兼容的。
+然而，我们建议在工作流文件中使用`gitea.xyz`，以防止在工作流文件中出现不同类型的密钥（因为您在Gitea上使用此工作流，而不是GitHub）。
+不过，这完全是可选的，因为目前这两个选项的效果是相同的。
+
+## 使用`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 上的？
+
+好消息是，您可以指定要从任何位置使用Actions的URL前缀。
+这是Gitea Actions中的额外语法。
+例如：
+
+- `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)。
+
+## 如何限制Runner的权限？
+
+Runner仅具有连接到您的Gitea实例的权限。
+当任何Runner接收到要运行的Job时，它将临时获得与Job关联的仓库的有限权限。
+如果您想为Runner提供更多权限，允许它访问更多私有仓库或外部系统，您可以向其传递[密钥](usage/actions/secrets.md)。
+
+对于 Actions 的细粒度权限控制是一项复杂的工作。
+在未来，我们将添加更多选项以使Gitea更可配置，例如允许对仓库进行更多写访问或对同一组织中的所有仓库进行读访问。
+
+## 如何避免被黑客攻击？
+
+有两种可能的攻击类型：未知的Runner窃取您的仓库中的代码或密钥，或恶意脚本控制您的Runner。
+
+避免前者意味着不允许您不认识的人为您的仓库、组织或实例注册Runner。
+
+后者要复杂一些。
+如果您为公司使用私有的Gitea实例，您可能不需要担心安全问题，因为您信任您的同事，并且可以追究他们的责任。
+
+对于公共实例，情况略有不同。
+以下是我们在 [gitea.com](http://gitea.com/)上的做法：
+
+- 我们仅为 "gitea" 组织注册Runner，因此我们的Runner不会执行来自其他仓库的Job。
+- 我们的Runner始终在隔离容器中运行Job。虽然可以直接在主机上进行这样的操作，但出于安全考虑，我们选择不这样做。
+- 对于 fork 的拉取请求，需要获得批准才能运行Actions。参见[#22803](https://github.com/go-gitea/gitea/pull/22803)。
+- 如果有人在[gitea.com](http://gitea.com/)为其仓库或组织注册自己的Runner，我们不会反对，只是不会在我们的组织中使用它。然而，他们应该注意确保该Runner不被他们不认识的其他用户使用。
+
+## act 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
+```
+
+## 为什么选择GitHub Actions？为什么不选择与GitLab CI/CD兼容的工具？
+
+[@lunny](https://gitea.com/lunny)在实现Actions的[问题](https://github.com/go-gitea/gitea/issues/13539)中已经解释过这个问题。
+此外，Actions不仅是一个CI/CD 系统，还是一个自动化工具。
+
+在开源世界中，已经有许多[市场上的Actions](https://github.com/marketplace?type=actions)实现了。
+能够重用它们是令人兴奋的。
+
+## 如果它在多个标签上运行，例如 `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尝试匹配标签中的每一个，并使用找到的第一个匹配项。
+
+## 代理标签和自定义标签对于Runner有什么区别？
+
+![labels](../../../static/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 Actions runner会有更多的实现吗？
+
+虽然我们希望提供更多的选择，但由于我们有限的人力资源，act runner将是唯一受支持的官方Runner。
+然而，无论您如何决定，Gitea 和act runner都是完全开源的，所以任何人都可以创建一个新的/更好的实现。
+我们支持您的选择，无论您如何决定。
+如果您选择分支act runner来创建自己的版本，请在您认为您的更改对其他人也有帮助的情况下贡献这些更改。
+
+## Gitea 支持哪些工作流触发事件？
+
+表格中列出的所有事件都是支持的，并且与 GitHub 兼容。
+对于仅 GitHub 支持的事件，请参阅 GitHub 的[文档](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows)。
+
+| 触发事件                    | 活动类型                                                                                                                 |
+|-----------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| create                      | 不适用                                                                                                                   |
+| delete                      | 不适用                                                                                                                   |
+| fork                        | 不适用                                                                                                                   |
+| gollum                      | 不适用                                                                                                                   |
+| push                        | 不适用                                                                                                                   |
+| issues                      | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `milestoned`, `demilestoned`, `labeled`, `unlabeled` |
+| issue_comment               | `created`, `edited`, `deleted`                                                                                           |
+| pull_request                | `opened`, `edited`, `closed`, `reopened`, `assigned`, `unassigned`, `synchronize`, `labeled`, `unlabeled`                |
+| pull_request_review         | `submitted`, `edited`                                                                                                    |
+| pull_request_review_comment | `created`, `edited`                                                                                                      |
+| release                     | `published`, `edited`                                                                                                    |
+| registry_package            | `published`                                                                                                              |
+
+> 对于 `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`，它指向这个拉取请求的头分支而不是合并提交的预览。
--- a/docs/document/usage/actions/overview.md
+++ b/docs/document/usage/actions/overview.md
@@ -0,0 +1,42 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "overview"
+sidebar_position: 1
+---
+
+# Overview
+
+从Gitea **1.19**版本开始，Gitea Actions成为了内置的CI/CD解决方案。
+
+## 名称
+
+Gitea Actions与[GitHub Actions](https://github.com/features/actions)相似且兼容，它的名称也受到了它的启发。
+为了避免混淆，在这里我们明确了拼写方式：
+
+- "Gitea Actions"（两个单词都大写且带有"s"）是Gitea功能的名称。
+- "GitHub Actions"是GitHub功能的名称。
+- "Actions"根据上下文的不同可以指代以上任意一个。在本文档中指代的是"Gitea Actions"。
+- "action"或"actions"指代一些要使用的脚本/插件，比如"actions/checkout@v4"或"actions/cache@v3"。
+
+## 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) 。
+
+由于Runner是独立部署的，可能存在潜在的安全问题。
+为了避免这些问题，请遵循两个简单的规则：
+
+- 不要为你的仓库、组织或实例使用你不信任的Runner。
+- 不要为你不信任的仓库、组织或实例提供Runner。
+
+对于内部使用的Gitea实例，比如企业或个人使用的实例，这两个规则不是问题，它们自然而然就是如此。
+然而，对于公共的Gitea实例，比如[gitea.com](https://gitea.com)，在添加或使用Runner时应当牢记这两个规则。
+
+## 状态
+
+Gitea Actions仍然在开发中，因此可能存在一些错误和缺失的功能。
+并且在稳定版本（v1.20或更高版本）之前可能会进行一些重大的更改。
+
+如果情况发生变化，我们将在此处进行更新。
+因此，请在其他地方找到过时文章时参考此处的内容。
--- a/docs/document/usage/actions/quickstart.md
+++ b/docs/document/usage/actions/quickstart.md
@@ -0,0 +1,131 @@
+---
+date: "2023-05-24T15:00:00+08:00"
+slug: "quickstart"
+sidebar_position: 10
+---
+
+# 快速入门
+
+本页面将指导您使用Gitea Actions的过程。
+
+## 设置Gitea
+
+首先，您需要一个Gitea实例。
+您可以按照[文档](installation/from-package.md) 来设置一个新实例或升级现有实例。
+无论您如何安装或运行Gitea，只要版本号是1.19.0或更高即可。
+
+从1.21.0开始，默认情况下，Actions是启用的。如果您正在使用1.21.0之前的版本，您需要将以下内容添加到配置文件中以启用它：
+
+```ini
+[actions]
+ENABLED=true
+```
+
+如果您想了解更多信息或在配置过程中遇到任何问题，请参考[配置速查表](../../administration/config-cheat-sheet.md#actions-actions)。
+
+### 设置Runner
+
+Gitea Actions需要[act runner](https://gitea.com/gitea/act_runner) 来运行Job。
+为了避免消耗过多资源并影响Gitea实例，建议您在与Gitea实例分开的机器上启动Runner。
+
+您可以使用[预构建的二进制文件](http://dl.gitea.com/act_runner)或[容器镜像](https://hub.docker.com/r/gitea/act_runner/tags)来设置Runner。
+
+在进一步操作之前，建议您先使用预构建的二进制文件以命令行方式运行它，以确保它与您的环境兼容，尤其是如果您在本地主机上运行Runner。
+如果出现问题，这样调试起来会更容易。
+
+该Runner可以在隔离的Docker容器中运行Job，因此您需要确保已安装Docker并且Docker守护进程正在运行。
+虽然这不是严格必需的，因为Runner也可以直接在主机上运行Job，这取决于您的配置方式。
+然而，建议使用Docker运行Job，因为它更安全且更易于管理。
+
+在运行Runner之前，您需要使用以下命令将其注册到Gitea实例中：
+
+```bash
+./act_runner register --no-interactive --instance <instance> --token <token>
+```
+
+需要两个必需的参数：`instance` 和 `token`。
+
+`instance`是您的Gitea实例的地址，如`http://192.168.8.8:3000`或`https://gitea.com`。
+Runner和Job容器（由Runner启动以执行Job）将连接到此地址。
+这意味着它可能与用于Web访问的`ROOT_URL`不同。
+使用回环地址（例如 `127.0.0.1` 或 `localhost`）是一个不好的选择。
+如果不确定使用哪个地址，通常选择局域网地址即可。
+
+`token` 用于身份验证和标识，例如 `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`。
+它只能使用一次，并且不能用于注册多个Runner。
+您可以从以下位置获取不同级别的`token`,从而创建出相应级别的`runner`
+
+- 实例级别：管理员设置页面，例如 `<your_gitea.com>/admin/actions/runners`。
+- 组织级别：组织设置页面，例如 `<your_gitea.com>/<org>/settings/actions/runners`。
+- 存储库级别：存储库设置页面，例如 `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`。
+
+![register runner](../../../static/images/usage/actions/register-runner.png)
+
+注册后，当前目录中将出现一个名为 `.runner` 的新文件，该文件存储了注册信息。
+请不要手动编辑该文件。
+如果该文件丢失或损坏，只需删除它然后重新注册即可。
+
+最后，是时候启动Runner了：
+
+```bash
+./act_runner daemon
+```
+
+您可以在管理页面上看到新的Runner：
+
+![view runner](../../../static/images/usage/actions/view-runner.png)
+
+您可以通过访问[act runner](usage/actions/act-runner.md) 获取更多信息。
+
+### 使用Actions
+
+即使对于启用了Gitea实例的Actions，存储库仍默认禁用Actions。
+
+要启用它，请转到存储库的设置页面，例如`your_gitea.com/<owner>/repo/settings`，然后启用`Enable Repository Actions`。
+
+![enable actions](../../../static/images/usage/actions/enable-actions.png)
+
+接下来的步骤可能相当复杂。
+您需要学习Actions的[工作流语法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions)，并编写您想要的工作流文件。
+
+不过，我们可以从一个简单的演示开始：
+
+```yaml
+name: Gitea Actions Demo
+run-name: ${{ gitea.actor }} is testing out Gitea Actions 🚀
+on: [push]
+
+jobs:
+  Explore-Gitea-Actions:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "🎉 The job was automatically triggered by a ${{ gitea.event_name }} event."
+      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by Gitea!"
+      - run: echo "🔎 The name of your branch is ${{ gitea.ref }} and your repository is ${{ gitea.repository }}."
+      - name: Check out repository code
+        uses: actions/checkout@v4
+      - run: echo "💡 The ${{ gitea.repository }} repository has been cloned to the runner."
+      - run: echo "🖥️ The workflow is now ready to test your code on the runner."
+      - name: List files in the repository
+        run: |
+          ls ${{ gitea.workspace }}
+      - run: echo "🍏 This job's status is ${{ job.status }}."
+```
+
+您可以将上述示例上传为一个以`.yaml`扩展名的文件，放在存储库的`.gitea/workflows/`目录中，例如`.gitea/workflows/demo.yaml`。
+您可能会注意到，这与[GitHub Actions的快速入门](https://docs.github.com/en/actions/quickstart)非常相似。
+这是因为Gitea Actions在尽可能兼容GitHub Actions的基础上进行设计。
+
+请注意，演示文件中包含一些表情符号。
+请确保您的数据库支持它们，特别是在使用MySQL时。
+如果字符集不是`utf8mb4`，将出现错误，例如`Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`。
+有关更多信息，请参阅[数据库准备工作](../../installation/database-preparation.md#mysqlmariadb)。
+
+或者，您可以从演示文件中删除所有表情符号，然后再尝试一次。
+
+`on: [push]` 这一行表示当您向该存储库推送提交时，工作流将被触发。
+然而，当您上传 YAML 文件时，它也会推送一个提交，所以您应该在"Actions"标签中看到一个新的任务。
+
+![view job](../../../static/images/usage/actions/view-job.png)
+
+做得好！您已成功开始使用Actions。
--- a/docs/document/usage/actions/secrets.md
+++ b/docs/document/usage/actions/secrets.md
@@ -0,0 +1,28 @@
+---
+date: "2023-05-23T09:00:00+08:00"
+slug: "secrets"
+sidebar_position: 50
+---
+
+# 密钥管理
+
+密钥管理允许您在用户、组织或仓库中存储敏感信息。
+密钥管理在 Gitea 1.19+ 版本中可用。
+
+## 设置密钥名称
+
+以下规则适用于密钥名称：
+
+- 密钥名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
+
+- 密钥名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
+
+- 密钥名称不能以数字开头。
+
+- 密钥名称不区分大小写。
+
+- 密钥名称在创建它们的级别上必须是唯一的。
+
+例如，对于在仓库级别创建的密钥，它在该仓库中必须具有唯一的名称；对于在组织级别创建的密钥，它在该级别上必须具有唯一的名称。
+
+如果在多个级别上存在具有相同名称的密钥，则最低级别的密钥优先生效。例如，如果组织级别的密钥与仓库级别的密钥具有相同的名称，则仓库级别的密钥将优先生效。
--- a/docs/document/usage/actions/variables.md
+++ b/docs/document/usage/actions/variables.md
@@ -0,0 +1,34 @@
+---
+date: "2024-04-10T22:21:00+08:00"
+slug: "actions-variables"
+sidebar_position: 25
+---
+
+# 变量
+
+您可以创建用户、组织和仓库级别的变量。变量的级别取决于创建它的位置。当创建变量时，变量的名称会被
+转换为大写，在yaml文件中引用时需要使用大写。
+
+## 命名规则
+
+以下规则适用于变量名：
+
+- 变量名称只能包含字母数字字符 (`[a-z]`, `[A-Z]`, `[0-9]`) 或下划线 (`_`)。不允许使用空格。
+- 变量名称不能以 `GITHUB_` 和 `GITEA_` 前缀开头。
+- 变量名称不能以数字开头。
+- 变量名称不区分大小写。
+- 变量名称在创建它们的级别上必须是唯一的。
+- 变量名称不能为 `CI`。
+
+## 使用
+
+创建配置变量后，它们将自动填充到 `vars` 上下文中。您可以在工作流中使用类似 
+```yaml
+${{ vars.VARIABLE_NAME }}
+```
+ 这样的表达式来使用它们。
+
+## 优先级
+
+如果同名变量存在于多个级别，则级别最低的变量优先。
+仓库级别的变量总是比组织或者用户级别的变量优先被选中。