跳至主要内容
版本：1.22.3

Act Runner

本页面将详细介绍 act runner，它是 Gitea Actions 的运行器。

需求​

目前，运行器支持两种运行模式。一种是在 Docker 容器中运行，另一种是在主机上运行。建议在 Docker 容器中运行作业，如果您选择此模式，则需要首先 安装 Docker 并确保 Docker 守护进程正在运行。

与 Docker API 兼容的其他 OCI 容器引擎也应该可以工作，但尚未经过测试。

但是，如果您确定只想直接在主机上运行作业，则不需要 Docker。

有多种方法可以安装 act runner。

使用二进制文件安装​

下载二进制文件​

您可以从 发布页面 下载二进制文件。但是，如果您想使用最新的 nightly 版本，则可以从 下载页面 下载。

下载二进制文件时，请确保已为您的平台下载了正确的文件。如果您使用的是类 Unix 操作系统，可以通过运行以下命令进行检查。

chmod +x act_runner
./act_runner --version

如果看到版本信息，则表示您已下载了正确的二进制文件。

获取注册令牌​

您可以在不同的级别注册运行器，可以是

  • 实例级别：运行器将为实例中的所有仓库运行作业。
  • 组织级别：运行器将为组织中的所有仓库运行作业。
  • 仓库级别：运行器将为其所属的仓库运行作业。

请注意，即使仓库有自己的仓库级运行器，它也可能仍然使用实例级或组织级运行器。未来的版本可能会提供一个选项，以便更好地控制这一点。

在注册运行器并运行它之前，您需要一个注册令牌。运行器的级别决定了从哪里获取注册令牌。

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

如果您看不到设置页面，请确保您具有正确的权限并且已启用 Actions。

注册令牌的格式是一个随机字符串 D0gvfu2iHfUjNqCYVljVyRV14fISpJxxxxxxxxxx。

还可以从 gitea 的 命令行界面 获取注册令牌。

gitea --config /etc/gitea/app.ini actions generate-runner-token

令牌有效期为注册多个运行器，直到它们被撤销并使用 Web 界面中的令牌重置链接替换为新令牌。

配置​

配置是通过配置文件完成的。它是可选的，当未指定配置文件时将使用默认配置。您可以通过运行以下命令生成配置文件

./act_runner generate-config

默认配置在没有任何修改的情况下是安全的，因此您可以直接使用它。

./act_runner generate-config > config.yaml
./act_runner --config config.yaml [command]

注册运行器​

在运行 act runner 之前需要进行注册，因为运行器需要知道从哪里获取作业。对于 Gitea 实例识别运行器也很重要。

如果已使用二进制软件包安装，则可以通过运行以下命令注册 act runner。

./act_runner register

或者，您可以使用 --config 选项指定上一节中提到的配置文件。

./act_runner --config config.yaml register

系统将逐步提示您输入注册信息，包括

  • Gitea 实例 URL，例如 https://gitea.com/ 或 http://192.168.8.8:3000/。
  • 注册令牌。
  • 运行器名称，可选。如果您将其留空，则将使用主机名。
  • 运行器标签，可选。如果您将其留空，则将使用默认标签。

您可能会对运行器标签感到困惑，稍后将对此进行解释。

如果您想以非交互方式注册运行器，则可以使用参数来执行此操作。

./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>

注册运行器后，您会在当前目录中找到一个名为 .runner 的新文件。此文件存储注册信息。请勿手动编辑它。如果此文件丢失或损坏，您可以简单地将其删除并重新注册。

如果您想将注册信息存储在其他位置，则可以在配置文件中指定它，并且不要忘记指定 --config 选项。

在命令行中启动运行器​

注册运行器后，可以通过运行以下命令启动它

./act_runner daemon

或

./act_runner daemon --config config.yaml

运行器将从 Gitea 实例中获取作业并自动运行它们。

使用 Systemd 启动运行器​

也可以将 act-runner 作为 systemd 服务运行。在您的系统上创建一个非特权 act_runner 用户，以及 /etc/systemd/system/act_runner.service 中的以下文件。根据您安装 act_runner 二进制文件的位置、其配置文件以及 act_runner 用户的主目录，可能需要调整 ExecStart 和 WorkingDirectory 中的路径。

[Unit]
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/act_runner
After=docker.service

[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=/var/lib/act_runner
TimeoutSec=0
RestartSec=10
Restart=always
User=act_runner

[Install]
WantedBy=multi-user.target

然后

# load the new systemd unit file
sudo systemctl daemon-reload
# start the service and enable it at boot
sudo systemctl enable act_runner --now

如果使用 Docker，则在启动服务之前还应将 act_runner 用户添加到 docker 组中。请记住，这实际上使 act_runner 对系统具有 root 访问权限 [1]。

使用 LaunchDaemon(macOS) 启动运行器​

Mac 使用 launchd 代替 systemd 来注册守护进程。默认情况下，守护进程以 root 用户身份运行，因此如果需要，可以通过 dscl 工具创建一个非特权 _act_runner 用户。然后，应在 /Library/LaunchDaemon/com.gitea.act_runner.plist 目录中创建以下文件。WorkingDirectory、ProgramArguments、StandardOutPath、StandardErrPath 和 HOME 环境变量的路径可能需要更新以反映您的安装情况。另请注意，任何不在显示的示例 PATH 之外的可执行文件都需要显式包含，并且不会从现有配置继承。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.gitea.act_runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/act_runner</string>
        <string>daemon</string>
        <string>--config</string>
        <string>/etc/act_runner/config.yaml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/var/lib/act_runner</string>
    <key>StandardOutPath</key>
    <string>/var/lib/act_runner/act_runner.log</string>
    <key>StandardErrorPath</key>
    <string>/var/lib/act_runner/act_runner.err</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>HOME></key>
        <string>/var/lib/act_runner</string>
    </dict>
    <key>UserName</key>
    <string>_act_runner</string>
</dict>
</plist>

然后

sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist

您还可以设置 Linux 服务或 Windows 服务以让运行器自动运行。

使用 Docker 镜像安装​

拉取镜像​

您可以从 Docker Hub 使用 Docker 镜像。就像二进制文件一样，您可以使用 nightly 标签使用最新的 nightly 版本，而 latest 标签是最新的稳定版本。

docker pull gitea/act_runner:latest # for the latest stable release

如果您想测试新功能，也可以使用 nightly 镜像

docker pull gitea/act_runner:nightly # for the latest nightly build

配置​

配置是可选的，但您也可以使用 Docker 生成配置文件

docker run --entrypoint="" --rm -it gitea/act_runner:latest act_runner generate-config > config.yaml

使用 Docker 镜像时，您可以使用 CONFIG_FILE 环境变量指定配置文件。确保将文件作为卷挂载到容器中

docker run -v $PWD/config.yaml:/config.yaml -e CONFIG_FILE=/config.yaml ...

您可能会注意到以上命令都不完整，因为现在还不是运行 act runner 的时候。在运行 act runner 之前，我们需要先将其注册到您的 Gitea 实例中。

使用 Docker 启动 Runner​

如果您使用的是 Docker 镜像，行为会略有不同。在这种情况下，注册和运行合并为一个步骤，因此您需要在运行 act runner 时指定注册信息。

使用以下 docker run 命令快速启动。您需要从上一步获取<registration_token>，并为<runner_name>指定一个唯一的名称。

docker run \
    -e GITEA_INSTANCE_URL=<instance_url> \
    -e GITEA_RUNNER_REGISTRATION_TOKEN=<registration_token> \
    -e GITEA_RUNNER_NAME=<runner_name> \
    --name my_runner \
    -d gitea/act_runner:nightly

还有更多参数可以用于配置。

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 容器中运行作业，因此它需要与 Docker 守护进程通信。如前所述，如果您希望直接在主机上运行作业，可以将其移除。需要明确的是，“主机”实际上指的是当前运行 act runner 的容器，而不是主机机器。

使用 Docker Compose 启动 Runner​

您也可以使用以下docker-compose.yml设置 Runner。

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 时，无需进入容器并手动运行./act_runner daemon命令，如下所示。容器成功启动后，它将显示为 Gitea 实例中的一个活动 Runner。

优势配置​

使用 Docker 镜像启动 Runner 时配置缓存​

如果您不打算在工作流中使用actions/cache，可以忽略此部分。

如果您使用actions/cache但没有任何额外的配置，它将返回以下错误

无法恢复：getCacheEntry 失败：连接 ETIMEDOUT IP:PORT

发生此错误的原因是 Runner 容器和作业容器位于不同的网络中，因此作业容器无法访问 Runner 容器。

因此，配置缓存操作以确保其正常运行至关重要。请按照以下步骤操作

  • 1.获取运行 Runner 容器的主机机器的 LAN IP 地址。
  • 2.找到运行 Runner 容器的主机机器上可用的端口号。
  • 3.在配置文件中配置以下设置
cache:
  enabled: true
  dir: ""
  # Use the LAN IP obtained in step 1
  host: "192.168.8.17"
  # Use the port number obtained in step 2
  port: 8088
  • 4.启动容器时，将缓存端口映射到主机机器
docker run \
  --name gitea-docker-runner \
  -p 8088:8088 \
  -d gitea/act_runner:nightly

标签​

Runner 的标签用于确定 Runner 可以运行哪些作业以及如何运行它们。

默认标签为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的作业，并且作业将在使用镜像node:16-bullseye的 Docker 容器中运行。

如果默认镜像不足以满足您的需求，并且您有足够的磁盘空间来使用更好更大的镜像，可以将其更改为ubuntu-22.04:docker://<您喜欢的镜像>。您可以在act images上找到更多有用的镜像。

如果您想直接在主机上运行作业，可以将其更改为ubuntu-22.04:host或仅ubuntu-22.04，:host是可选的。但是，我们建议您使用特殊的名称，例如linux_amd64:host或windows:host，以避免误用。

从 Gitea 1.21 开始，您可以通过修改 Runner 配置文件中的container.labels来更改标签（如果您没有配置文件，请参考配置教程）。一旦您重新启动 Runner（例如，通过调用./act_runner daemon --config config.yaml），它将立即使用这些新标签。