Act Runner
本頁將詳細介紹 act runner,這是 Gitea Actions 的 runner。
要求
目前 runner 支持兩種運行模式。一種是在 docker 容器中運行,另一種是在主機上運行。如果選擇在 docker 容器中運行作業,建議先 安裝 docker 並確保 docker 守護進程正在運行。
其他與 Docker API 兼容的 OCI 容器引擎也應該可以工作,但未經測試。
但是,如果您確定只想在主機上直接運行作業,則不需要 docker。
有多種方法可以安裝 act runner。
使用二進制文件安裝
下載二進制文件
您可以從 發布頁面 下載二進制文件。 但是,如果您想使用最新的夜間構建,可以從 下載頁面 下載。
下載二進制文件時,請確保下載了適合您平台的正確文件。 如果您使用的是類 Unix 操作系統,可以通過運行以下命令進行檢查。
chmod +x act_runner
./act_runner --version
如果看到版本信息,則表示您已下載了正確的二進制文件。
獲取註冊令牌
您可以在不同級別註冊 runner,它可以是:
- 實例級別:runner 將為實例中的所有倉庫運行作業。
- 組織級別:runner 將為組織中的所有倉庫運行作業。
- 倉庫級別:runner 將為其所屬的倉庫運行作業。
請注意,即使倉庫有自己的倉庫級別 runner,它仍然可以使用實例級別或組織級別的 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 命令行界面 獲取:
gitea --config /etc/gitea/app.ini actions generate-runner-token
令牌在註銷並使用 web 界面中的令牌重置鏈接替換為新令牌之前,對註冊多個 runner 有效。
配置
配置是通過配置文件完成的。它是可選的,當未指定配置文件時,將使用默認配置。您可以通過運行以下命令生成配置文件:
./act_runner generate-config
默認配置是安全的,可以直接使用。
./act_runner generate-config > config.yaml
./act_runner --config config.yaml [command]
註冊 runner
在運行 act runner 之前需要註冊,因為 runner 需要知道從哪裡獲取作業。這對於 Gitea 實例識別 runner 也很重要。
如果使用二進制包安裝,可以通過運行以下命令註冊 act runner。
./act_runner register
或者,您可以使用 --config
選項指定前面提到的配置文件。
./act_runner --config config.yaml register
您將被要求逐步輸入註冊信息,包括:
- Gitea 實例 URL,例如
https://gitea.com/
或http://192.168.8.8:3000/
。 - 註冊令牌。
- runner 名稱,可選。如果留空,將使用主機名。
- runner 標籤,可選。如果留空,將使用默認標籤。
您可能會對 runner 標籤感到困惑,稍後將解釋。
如果您想以非交互方式註冊 runner,可以使用參數進行註冊。
./act_runner register --no-interactive --instance <instance_url> --token <registration_token> --name <runner_name> --labels <runner_labels>
註冊 runner 後,您可以在當前目錄中找到一個名為 .runner
的新文件。
該文件存儲註冊信息。
請不要手動編輯它。
如果該文件丟失或損壞,您可以簡單地刪除它並重新註冊。
如果您想將註冊信息存儲在其他位置,可以在配置文件中指定,
並且不要忘記指定 --config
選項。
在命令行中啟動 runner
註冊 runner 後,可以通過運行以下命令運行它:
./act_runner daemon
或
./act_runner daemon --config config.yaml
runner 將從 Gitea 實例中獲取作業並自動運行它們。
使用 Systemd 啟動 runner
也可以將 act-runner 作為 systemd 服務運行。在系統上創建一個非特權的 act_runner
用戶,並在 /etc/systemd/system/act_runner.service
中創建以下文件。ExecStart
和 WorkingDirectory
中的路徑可能需要根據您安裝 act_runner
二進制文件、其配置文件和 act_runner
用戶的主目錄進行調整。
[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
然後:
# 加載新的 systemd 單元文件
sudo systemctl daemon-reload
# 啟動服務並在啟動時啟用它
sudo systemctl enable act_runner --now
如果使用 Docker,應在啟動服務之前將 act_runner
用戶添加到 docker
組。請記住,這實際上給了 act_runner
對系統的 root 訪問權限 [1]。
使用 LaunchDaemon(macOS) 啟動 runner
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 服務,以便 runner 自動運行。
使用 docker 映像安裝
拉取映像
您可以從 docker hub 使用 docker 映像。
就像二進制文件一樣,您可以使用 nightly
標籤使用最新的夜間構建,而 latest
標籤是最新的穩定版本。
docker pull docker.io/gitea/act_runner:latest # 用於最新的穩定版本
如果您想測試新功能,也可以使用 nightly 映像
docker pull docker.io/gitea/act_runner:nightly # 用於最新的夜間構建
配置
配置是可選的,但您也可以使用 docker 生成配置文件:
docker run --entrypoint="" --rm -it docker.io/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 docker.io/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 docker.io/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: docker.io/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
,它將返回以下錯誤:
Failed to restore: getCacheEntry failed: connect ETIMEDOUT IP:PORT
發生此錯誤是因為 runner 容器和作業容器位於不同的網絡上,因此作業容器無法訪問 runner 容器。
因此,必須配置緩存操作以確保其正常運行。請按照以下步驟操作:
- 1.獲取運行 runner 容器的主機的 LAN IP 地址。
- 2.查找運行 runner 容器的主機上的可用端口號。
- 3.在配置文件中配置以下設置:
cache:
enabled: true
dir: ""
# 使用第 1 步中獲取的 LAN IP
host: "192.168.8.17"
# 使用第 2 步中獲取的端口號
port: 8088
- 4.啟動容器時,將緩存端口映射到主機:
docker run \
--name gitea-docker-runner \
-p 8088:8088 \
-d docker.io/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
的作業,並且作業將在 docker 容器中運行,映像為 node:16-bullseye
。
如果默認映像不足以滿足您的需求,並且您有足夠的磁盤空間使用更好更大的映像,可以將其更改為 ubuntu-22.04:docker://<the image you like>
。
您可以在 act images 上找到更多有用的映像。
如果您想在主機上直接運行作業,可以將其更改為 ubuntu-22.04:host
或僅 ubuntu-22.04
,:host
是可選的。
但是,我們建議您使用一個特殊的名稱,如 linux_amd64:host
或 windows:host
以避免誤用。
從 Gitea 1.21 開始,您可以通過修改 runner 配置文件中的 runners.labels
來更改標籤(如果您沒有配置文件,請參考 配置教程)。
重新啟動 runner 後,它將使用這些新標籤,即通過調用 ./act_runner daemon --config config.yaml
。