mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-20 04:58:52 +00:00
docs: add zh-tw folder (#195)
Signed-off-by: appleboy <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/195 Reviewed-by: Lunny Xiao <[email protected]> Co-authored-by: appleboy <[email protected]> Co-committed-by: appleboy <[email protected]>
This commit is contained in:
appleboy
Lunny Xiao
@@ -0,0 +1,366 @@
|
||||
---
|
||||
date: "2023-04-27T15:00:00+08:00"
|
||||
slug: "act-runner"
|
||||
sidebar_position: 20
|
||||
---
|
||||
|
||||
# Act Runner
|
||||
|
||||
本頁將詳細介紹 [act runner](https://gitea.com/gitea/act_runner)，這是 Gitea Actions 的 runner。
|
||||
|
||||
## 要求
|
||||
|
||||
目前 runner 支持兩種運行模式。一種是在 docker 容器中運行，另一種是在主機上運行。如果選擇在 [docker](https://docker.com) 容器中運行作業，建議先 [安裝 docker](https://docs.docker.com/engine/install/) 並確保 docker 守護進程正在運行。
|
||||
|
||||
其他與 Docker API 兼容的 OCI 容器引擎也應該可以工作，但未經測試。
|
||||
|
||||
但是，如果您確定只想在主機上直接運行作業，則不需要 docker。
|
||||
|
||||
有多種方法可以安裝 act runner。
|
||||
|
||||
## 使用二進制文件安裝
|
||||
|
||||
### 下載二進制文件
|
||||
|
||||
您可以從 [發布頁面](https://gitea.com/gitea/act_runner/releases) 下載二進制文件。
|
||||
但是，如果您想使用最新的夜間構建，可以從 [下載頁面](https://dl.gitea.com/act_runner/) 下載。
|
||||
|
||||
下載二進制文件時，請確保下載了適合您平台的正確文件。
|
||||
如果您使用的是類 Unix 操作系統，可以通過運行以下命令進行檢查。
|
||||
|
||||
```bash
|
||||
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 [命令行界面](../../administration/command-line.md#actions-generate-runner-token) 獲取：
|
||||
|
||||
```
|
||||
gitea --config /etc/gitea/app.ini actions generate-runner-token
|
||||
```
|
||||
|
||||
令牌在註銷並使用 web 界面中的令牌重置鏈接替換為新令牌之前，對註冊多個 runner 有效。
|
||||
|
||||
### 配置
|
||||
|
||||
配置是通過配置文件完成的。它是可選的，當未指定配置文件時，將使用默認配置。您可以通過運行以下命令生成配置文件：
|
||||
|
||||
```bash
|
||||
./act_runner generate-config
|
||||
```
|
||||
|
||||
默認配置是安全的，可以直接使用。
|
||||
|
||||
```bash
|
||||
./act_runner generate-config > config.yaml
|
||||
./act_runner --config config.yaml [command]
|
||||
```
|
||||
|
||||
### 註冊 runner
|
||||
|
||||
在運行 act runner 之前需要註冊，因為 runner 需要知道從哪裡獲取作業。這對於 Gitea 實例識別 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` 選項。
|
||||
|
||||
### 在命令行中啟動 runner
|
||||
|
||||
註冊 runner 後，可以通過運行以下命令運行它：
|
||||
|
||||
```shell
|
||||
./act_runner daemon
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```bash
|
||||
./act_runner daemon --config config.yaml
|
||||
```
|
||||
|
||||
runner 將從 Gitea 實例中獲取作業並自動運行它們。
|
||||
|
||||
### 使用 Systemd 啟動 runner
|
||||
|
||||
也可以將 act-runner 作為 [systemd](https://en.wikipedia.org/wiki/Systemd) 服務運行。在系統上創建一個非特權的 `act_runner` 用戶，並在 `/etc/systemd/system/act_runner.service` 中創建以下文件。`ExecStart` 和 `WorkingDirectory` 中的路徑可能需要根據您安裝 `act_runner` 二進制文件、其配置文件和 `act_runner` 用戶的主目錄進行調整。
|
||||
|
||||
```ini
|
||||
[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
|
||||
```
|
||||
|
||||
然後：
|
||||
|
||||
```bash
|
||||
# 加載新的 systemd 單元文件
|
||||
sudo systemctl daemon-reload
|
||||
# 啟動服務並在啟動時啟用它
|
||||
sudo systemctl enable act_runner --now
|
||||
```
|
||||
|
||||
如果使用 Docker，應在啟動服務之前將 `act_runner` 用戶添加到 `docker` 組。請記住，這實際上給了 `act_runner` 對系統的 root 訪問權限 [[1]](https://docs.docker.com/engine/security/#docker-daemon-attack-surface)。
|
||||
|
||||
### 使用 LaunchDaemon(macOS) 啟動 runner
|
||||
|
||||
Mac 使用 `launchd` 代替 systemd 註冊守護進程。默認情況下，守護進程以 root 用戶身份運行，因此如果需要，可以通過 `dscl` 工具創建一個非特權的 `_act_runner` 用戶。然後應在 `/Library/LaunchDaemon/com.gitea.act_runner.plist` 目錄中創建以下文件。`WorkingDirectory`、`ProgramArguments`、`StandardOutPath`、`StandardErrPath` 和 `HOME` 環境變量的路徑可能需要更新以反映您的安裝。此外，任何不在示例 `PATH` 中的可執行文件都需要顯式包含，並且不會從現有配置中繼承。
|
||||
|
||||
```xml
|
||||
<?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>
|
||||
```
|
||||
|
||||
然後：
|
||||
|
||||
```bash
|
||||
sudo launchctl load /Library/LaunchDaemon/com.gitea.act_runner.plist
|
||||
```
|
||||
|
||||
您還可以設置 Linux 服務或 Windows 服務，以便 runner 自動運行。
|
||||
|
||||
## 使用 docker 映像安裝
|
||||
|
||||
### 拉取映像
|
||||
|
||||
您可以從 [docker hub](https://hub.docker.com/r/gitea/act_runner/tags) 使用 docker 映像。
|
||||
就像二進制文件一樣，您可以使用 `nightly` 標籤使用最新的夜間構建，而 `latest` 標籤是最新的穩定版本。
|
||||
|
||||
```bash
|
||||
docker pull docker.io/gitea/act_runner:latest # 用於最新的穩定版本
|
||||
```
|
||||
|
||||
如果您想測試新功能，也可以使用 nightly 映像
|
||||
|
||||
```bash
|
||||
docker pull docker.io/gitea/act_runner:nightly # 用於最新的夜間構建
|
||||
```
|
||||
|
||||
### 配置
|
||||
|
||||
配置是可選的，但您也可以使用 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 實例。
|
||||
|
||||
### 使用 docker 啟動 runner
|
||||
|
||||
如果您使用的是 docker 映像，行為會略有不同。在這種情況下，註冊和運行結合為一步，因此您需要在運行 act runner 時指定註冊信息。
|
||||
|
||||
使用 docker run 快速啟動如下。您需要從上述步驟中獲取 `<registration_token>`，並為 `<runner_name>` 提供一個特殊的唯一名稱
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
有更多參數可以配置它。
|
||||
|
||||
```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 docker.io/gitea/act_runner:nightly
|
||||
```
|
||||
|
||||
您可能會注意到我們已將 `/var/run/docker.sock` 掛載到容器中。
|
||||
這是因為 act runner 將在 docker 容器中運行作業，因此需要與 docker 守護進程通信。
|
||||
如前所述，如果您想在主機上直接運行作業，可以刪除它。
|
||||
需要明確的是，“主機”實際上是指現在運行 act runner 的容器，而不是主機機器。
|
||||
|
||||
### 使用 docker compose 啟動 runner
|
||||
|
||||
您還可以使用以下 `docker-compose.yml` 設置 runner：
|
||||
|
||||
```yml
|
||||
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.在配置文件中配置以下設置：
|
||||
|
||||
```yaml
|
||||
cache:
|
||||
enabled: true
|
||||
dir: ""
|
||||
# 使用第 1 步中獲取的 LAN IP
|
||||
host: "192.168.8.17"
|
||||
# 使用第 2 步中獲取的端口號
|
||||
port: 8088
|
||||
```
|
||||
|
||||
- 4.啟動容器時，將緩存端口映射到主機：
|
||||
|
||||
```bash
|
||||
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](https://github.com/nektos/act/blob/master/IMAGES.md) 上找到更多有用的映像。
|
||||
|
||||
如果您想在主機上直接運行作業，可以將其更改為 `ubuntu-22.04:host` 或僅 `ubuntu-22.04`，`:host` 是可選的。
|
||||
但是，我們建議您使用一個特殊的名稱，如 `linux_amd64:host` 或 `windows:host` 以避免誤用。
|
||||
|
||||
從 Gitea 1.21 開始，您可以通過修改 runner 配置文件中的 `runners.labels` 來更改標籤（如果您沒有配置文件，請參考 [配置教程](#configuration)）。
|
||||
重新啟動 runner 後，它將使用這些新標籤，即通過調用 `./act_runner daemon --config config.yaml`。
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
date: "2023-02-25T00:00:00+00:00"
|
||||
slug: "badge"
|
||||
sidebar_position: 110
|
||||
---
|
||||
|
||||
# 徽章
|
||||
|
||||
Gitea 內置了徽章系統，允許您在其他地方顯示倉庫的狀態。您可以使用以下徽章：
|
||||
|
||||
## 工作流程徽章
|
||||
|
||||
Gitea Actions 工作流程徽章是一個顯示最新工作流程運行狀態的徽章。
|
||||
它設計為與 [GitHub Actions 工作流程徽章](https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge) 兼容。
|
||||
|
||||
您可以使用以下 URL 獲取徽章：
|
||||
|
||||
```
|
||||
https://your-gitea-instance.com/{owner}/{repo}/actions/workflows/{workflow_file}/badge.svg?branch={branch}&event={event}
|
||||
```
|
||||
|
||||
- `{owner}`: 倉庫的所有者。
|
||||
- `{repo}`: 倉庫的名稱。
|
||||
- `{workflow_file}`: 工作流程文件的名稱。
|
||||
- `{branch}`: 可選。工作流程的分支。默認為倉庫的默認分支。
|
||||
- `{event}`: 可選。工作流程的事件。默認為無。
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
date: "2023-04-27T15:00:00+08:00"
|
||||
slug: "comparison"
|
||||
sidebar_position: 120
|
||||
---
|
||||
|
||||
# 與 GitHub Actions 的比較
|
||||
|
||||
儘管 Gitea Actions 設計為與 GitHub Actions 兼容，但它們之間仍存在一些差異。
|
||||
|
||||
## 附加功能
|
||||
|
||||
### 絕對操作 URL
|
||||
|
||||
Gitea Actions 支持通過絕對 URL 定義操作，這意味著您可以使用來自任何 git 倉庫的操作。
|
||||
例如 `uses: https://github.com/actions/checkout@v4` 或 `uses: http://your_gitea.com/owner/repo@branch`。
|
||||
|
||||
### 用 Go 編寫的操作
|
||||
|
||||
Gitea Actions 支持用 Go 編寫操作。
|
||||
請參閱 [創建 Go 操作](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`
|
||||
|
||||
用於一次運行一個作業。
|
||||
請參閱 [使用並發](https://docs.github.com/en/actions/using-jobs/using-concurrency)。
|
||||
|
||||
目前 Gitea Actions 忽略它。
|
||||
|
||||
### `run-name`
|
||||
|
||||
從工作流程生成的工作流程運行的名稱。
|
||||
請參閱 [GitHub Actions 的工作流程語法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#run-name)。
|
||||
|
||||
目前 Gitea Actions 忽略它。
|
||||
|
||||
### `permissions` 和 `jobs.<job_id>.permissions`
|
||||
|
||||
請參閱 [GitHub Actions 的工作流程語法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions)。
|
||||
|
||||
目前 Gitea Actions 忽略它。
|
||||
|
||||
### `jobs.<job_id>.timeout-minutes`
|
||||
|
||||
請參閱 [GitHub Actions 的工作流程語法](https://docs.github.com/en/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/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idcontinue-on-error)。
|
||||
|
||||
目前 Gitea Actions 忽略它。
|
||||
|
||||
### `jobs.<job_id>.environment`
|
||||
|
||||
請參閱 [GitHub Actions 的工作流程語法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment)。
|
||||
|
||||
目前 Gitea Actions 忽略它。
|
||||
|
||||
### 複雜的 `runs-on`
|
||||
|
||||
請參閱 [GitHub Actions 的工作流程語法](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on)。
|
||||
|
||||
目前 Gitea Actions 只支持 `runs-on: xyz` 或 `runs-on: [xyz]`。
|
||||
|
||||
## 缺少的功能
|
||||
|
||||
### 包倉庫授權
|
||||
|
||||
在倉庫內運行的作業的 `GITEA_TOKEN` 應該能夠發布到相關的包倉庫（即上傳 OCI 映像）。請參閱 [自動令牌身份驗證](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) 中的“包”範圍的“默認訪問”。
|
||||
|
||||
目前 Gitea Actions 尚未實現此功能。Gitea Actions 的一個解決方法是使用個人訪問令牌（PAT）。請參閱此 [github 問題和評論](https://github.com/go-gitea/gitea/issues/23642#issuecomment-2119876692) 以跟踪此功能。
|
||||
|
||||
### 問題匹配器
|
||||
|
||||
問題匹配器是一種掃描操作輸出以查找指定正則表達式模式並在 UI 中突出顯示該信息的方法。
|
||||
請參閱 [問題匹配器](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md)。
|
||||
|
||||
目前 Gitea Actions 忽略它。
|
||||
|
||||
### 創建錯誤註釋
|
||||
|
||||
請參閱 [為錯誤創建註釋](https://docs.github.com/en/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 功能
|
||||
|
||||
### 預處理和後處理步驟
|
||||
|
||||
預處理和後處理步驟在作業日誌用戶界面中沒有自己的部分。
|
||||
|
||||
### 服務步驟
|
||||
|
||||
服務步驟在作業日誌用戶界面中沒有自己的部分。
|
||||
|
||||
## 不同的行為
|
||||
|
||||
### 下載操作
|
||||
|
||||
以前（1.21.0 之前），`[actions].DEFAULT_ACTIONS_URL` 默認為 `https://gitea.com`。
|
||||
我們已經限制了此選項僅允許兩個值（`github` 和 `self`）。
|
||||
當設置為 `github` 時，新的默認值，Gitea 將從 `https://github.com` 下載非完全限定的操作。
|
||||
例如，如果您使用 `uses: actions/checkout@v4`，它將從 `https://github.com/actions/checkout.git` 下載 checkout 倉庫。
|
||||
|
||||
如果您想從其他 git 託管服務器下載操作，可以使用絕對 URL，例如 `uses: https://gitea.com/actions/checkout@v4`。
|
||||
|
||||
如果您的 Gitea 實例位於內部網或受限區域，您可以將 URL 設置為 `self`，以便默認僅從您自己的實例下載操作。
|
||||
當然，您仍然可以在工作流程中使用絕對 URL。
|
||||
|
||||
有關 `[actions].DEFAULT_ACTIONS_URL` 配置的更多詳細信息，請參閱 [配置備忘單](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
|
||||
### 上下文可用性
|
||||
|
||||
不檢查上下文可用性，因此您可以在更多地方使用 env 上下文。
|
||||
請參閱 [上下文可用性](https://docs.github.com/en/actions/learn-github-actions/contexts#context-availability)。
|
||||
@@ -0,0 +1,122 @@
|
||||
---
|
||||
date: "2023-04-27T15:00:00+08:00"
|
||||
slug: "design"
|
||||
sidebar_position: 140
|
||||
---
|
||||
|
||||
# Gitea Actions 的設計
|
||||
|
||||
Gitea Actions 有多個組件。本文件將分別描述它們。
|
||||
|
||||
## Act
|
||||
|
||||
[nektos/act](https://github.com/nektos/act) 項目是一個出色的工具，允許您在本地運行 GitHub Actions。
|
||||
我們受此啟發，想知道是否可以為 Gitea 運行操作。
|
||||
|
||||
然而，雖然 [nektos/act](https://github.com/nektos/act) 被設計為命令行工具，但我們實際上需要的是一個專門為 Gitea 進行修改的 Go 庫。
|
||||
所以我們將其分叉為 [gitea/act](https://gitea.com/gitea/act)。
|
||||
|
||||
這是一個軟分叉，將定期跟隨上游。
|
||||
儘管添加了一些自定義提交，但我們將盡量避免更改太多原始代碼。
|
||||
|
||||
分叉的 act 只是 Gitea 特定用法的 shim 或適配器。
|
||||
已經進行了一些額外的提交，例如：
|
||||
|
||||
- 將執行日誌輸出到 logger 鉤子，以便可以報告給 Gitea
|
||||
- 禁用 GraphQL URL，因為 Gitea 不支持它
|
||||
- 為每個作業啟動一個新容器，而不是重用，以確保隔離。
|
||||
|
||||
這些修改沒有理由合併到上游。
|
||||
如果用戶只想在本地運行受信任的操作，這些修改沒有意義。
|
||||
|
||||
然而，未來可能會有重疊，例如兩個項目都需要的錯誤修復或新功能。
|
||||
在這些情況下，我們將把更改貢獻回上游倉庫。
|
||||
|
||||
## Act runner
|
||||
|
||||
Gitea 的 runner 被稱為 act runner，因為它基於 act。
|
||||
|
||||
像其他 CI runner 一樣，我們將其設計為 Gitea 的外部部分，這意味著它應該在與 Gitea 不同的服務器上運行。
|
||||
|
||||
為了確保 runner 連接到正確的 Gitea 實例，我們需要使用令牌註冊它。
|
||||
此外，runner 將向 Gitea 介紹自己並通過報告其標籤來聲明它可以運行的作業類型。
|
||||
|
||||
前面提到過，工作流程文件中的 `runs-on: ubuntu-latest` 意味著作業將在具有 `ubuntu-latest` 標籤的 runner 上運行。
|
||||
但是 runner 如何知道運行 `ubuntu-latest`？答案在於將標籤映射到環境。
|
||||
這就是為什麼在註冊期間添加自定義標籤時，您需要輸入一些複雜的內容，如 `my_custom_label:docker://centos:7`。
|
||||
這意味著 runner 可以接受需要在 `my_custom_label` 上運行的作業，並將其通過 docker 容器運行，映像為 `centos:7`。
|
||||
|
||||
然而，docker 並不是唯一的選擇。
|
||||
act 還支持直接在主機上運行作業。
|
||||
這是通過標籤如 `linux_arm:host` 實現的。
|
||||
這個標籤表示 runner 可以接受需要在 `linux_arm` 上運行的作業，並直接在主機上運行它。
|
||||
|
||||
標籤的設計遵循格式 `label[:schema[:args]]`。
|
||||
如果省略 schema，則默認為 `host`。
|
||||
所以，
|
||||
|
||||
- `my_custom_label:docker://node:18`: 使用 `node:18` Docker 映像運行標籤為 `my_custom_label` 的作業。
|
||||
- `my_custom_label:host`: 直接在主機上運行標籤為 `my_custom_label` 的作業。
|
||||
- `my_custom_label`: 與 `my_custom_label:host` 相同。
|
||||
- `my_custom_label:vm:ubuntu-latest`: （僅示例，未實現）使用 `ubuntu-latest` ISO 的虛擬機運行標籤為 `my_custom_label` 的作業。
|
||||
|
||||
## 通信協議
|
||||
|
||||
由於 act runner 是 Gitea 的獨立部分，我們需要一個協議來讓 runner 與 Gitea 實例通信。
|
||||
然而，我們認為讓 Gitea 監聽一個新端口不是一個好主意。
|
||||
相反，我們希望重用 HTTP 端口，這意味著我們需要一個與 HTTP 兼容的協議。
|
||||
我們選擇使用 gRPC over HTTP。
|
||||
|
||||
我們使用 [actions-proto-def](https://gitea.com/gitea/actions-proto-def) 和 [actions-proto-go](https://gitea.com/gitea/actions-proto-go) 來將它們連接起來。
|
||||
有關 gRPC 的更多信息可以在 [其網站](https://grpc.io/) 上找到。
|
||||
|
||||
## 網絡架構
|
||||
|
||||
讓我們來看看整體網絡架構。
|
||||
這將幫助您排除一些問題，並解釋為什麼用 Gitea 實例的回環地址註冊 runner 是個壞主意。
|
||||
|
||||
|
||||
|
||||
圖片中標記了四個網絡連接，箭頭的方向表示建立連接的方向。
|
||||
|
||||
### 連接 1，act runner 到 Gitea 實例
|
||||
|
||||
act runner 必須能夠連接到 Gitea 以接收任務並發送回執行結果。
|
||||
|
||||
### 連接 2，作業容器到 Gitea 實例
|
||||
|
||||
作業容器與 runner 有不同的網絡命名空間，即使它們在同一台機器上。
|
||||
如果工作流程中有 `actions/checkout@v4`，它們需要連接到 Gitea 以獲取代碼。
|
||||
運行某些作業並不總是需要獲取代碼，但在大多數情況下是必需的。
|
||||
|
||||
如果您使用回環地址註冊 runner，當它在同一台機器上時，runner 可以連接到 Gitea。
|
||||
但是，如果作業容器嘗試從 localhost 獲取代碼，則會失敗，因為 Gitea 不在同一容器中。
|
||||
|
||||
### 連接 3，act runner 到互聯網
|
||||
|
||||
當您使用一些操作如 `actions/checkout@v4` 時，act runner 會下載腳本，而不是作業容器。
|
||||
默認情況下，它從 [github.com](http://github.com/) 下載，因此需要訪問互聯網。如果您將 `DEFAULT_ACTIONS_URL` 配置為 `self`，則它將默認從您的 Gitea 實例下載。然後在下載操作本身時不會連接到互聯網。
|
||||
它還默認從 Docker Hub 下載一些 docker 映像，這也需要訪問互聯網。
|
||||
|
||||
然而，訪問互聯網並不是絕對必要的。
|
||||
您可以配置您的 Gitea 實例從您的內聯設施中獲取操作或映像。
|
||||
|
||||
事實上，您的 Gitea 實例可以同時作為操作市場和映像註冊表。
|
||||
您可以將操作倉庫從 GitHub 鏡像到您的 Gitea 實例，並正常使用它們。
|
||||
而 [Gitea 容器註冊表](usage/packages/container.md) 可以用作 Docker 映像註冊表。
|
||||
|
||||
### 連接 4，作業容器到互聯網
|
||||
|
||||
當使用如 `actions/setup-go@v5` 的操作時，可能需要從互聯網下載資源以在作業容器中設置 Go 語言環境。
|
||||
因此，訪問互聯網是這些操作成功完成所必需的。
|
||||
|
||||
然而，這也是可選的。
|
||||
您可以使用自己的自定義操作來避免依賴互聯網訪問，或者您可以使用打包的 Docker 映像來運行已安裝所有依賴項的作業。
|
||||
|
||||
## 總結
|
||||
|
||||
使用 Gitea Actions 只需要確保 runner 可以連接到 Gitea 實例。
|
||||
訪問互聯網是可選的，但沒有它將需要一些額外的工作。
|
||||
換句話說：runner 最好能夠自己查詢互聯網，但您不需要將其暴露在互聯網上（無論是入站還是出站）。
|
||||
|
||||
如果您在使用 Gitea Actions 時遇到任何網絡問題，希望上圖可以幫助您排除它們。
|
||||
@@ -0,0 +1,166 @@
|
||||
---
|
||||
date: "2023-04-27T15:00:00+08:00"
|
||||
slug: "faq"
|
||||
sidebar_position: 200
|
||||
---
|
||||
|
||||
# 常見問題
|
||||
|
||||
這頁包含了一些關於 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 沒有的功能，避免在工作流程文件中出現不同種類的 secrets（而且你是在 Gitea 上使用這個工作流程，而不是 GitHub）。
|
||||
不過，這完全是可選的，因為目前兩者的效果相同。
|
||||
|
||||
## 使用 `actions/checkout@v4` 等 actions 時，runner 會下載腳本到哪裡？
|
||||
|
||||
在 GitHub 上有成千上萬的 [actions 腳本](https://github.com/marketplace?type=actions)，當你寫 `uses: actions/checkout@v4` 時，它會默認從 [github.com/actions/checkout](http://github.com/actions/checkout) 下載腳本。
|
||||
但如果你想從其他地方（如 gitea.com）而不是 GitHub 使用 actions 怎麼辦？
|
||||
|
||||
好消息是你可以指定 URL 前綴來從任何地方使用 actions。
|
||||
這是 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 腳本。
|
||||
但這應該允許用戶在運行 Actions 時有更多的靈活性。
|
||||
|
||||
另外，如果你希望你的 runners 默認從你自己的 Gitea 實例下載 actions，你可以通過設置 `[actions].DEFAULT_ACTIONS_URL` 來配置。
|
||||
參見 [配置備忘單](../../administration/config-cheat-sheet.md#actions-actions)。
|
||||
|
||||
## 如何限制 runners 的權限？
|
||||
|
||||
Runners 只具有連接到你的 Gitea 實例的權限。
|
||||
當任何 runner 接收到一個要運行的任務時，它將臨時獲得與該任務相關的倉庫的有限權限。
|
||||
如果你想給 runner 更多的權限，允許它訪問更多的私有倉庫或外部系統，你可以傳遞 [secrets](usage/actions/secrets.md) 給它。
|
||||
|
||||
對 Actions 進行精細的權限控制是一項複雜的工作。
|
||||
未來，我們將為 Gitea 添加更多選項，使其更具可配置性，例如允許更多的寫入訪問倉庫或讀取同一組織中所有倉庫的訪問權限。
|
||||
|
||||
## 如何避免被黑客攻擊？
|
||||
|
||||
有兩種類型的可能攻擊：未知的 runner 竊取你的倉庫中的代碼或 secrets，或惡意腳本控制你的 runner。
|
||||
|
||||
避免前者意味著不允許你不認識的人為你的倉庫、組織或實例註冊 runners。
|
||||
|
||||
後者則有點複雜。
|
||||
如果你為你的公司使用私人 Gitea 實例，你可能不需要擔心安全問題，因為你信任你的同事並且可以追究他們的責任。
|
||||
|
||||
對於公共實例，情況有點不同。
|
||||
以下是我們在 [gitea.com](http://gitea.com/) 上的做法：
|
||||
|
||||
- 我們只為 "gitea" 組織註冊 runners，因此我們的 runners 不會執行來自其他倉庫的任務。
|
||||
- 我們的 runners 總是使用隔離的容器運行任務。雖然可以直接在主機上這樣做，但我們選擇不這樣做以提高安全性。
|
||||
- 要運行 fork pull requests 的 actions，需要批准。參見 [#22803](https://github.com/go-gitea/gitea/pull/22803)。
|
||||
- 如果有人在 [gitea.com](http://gitea.com/) 上為他們的倉庫或組織註冊了他們自己的 runner，我們不反對，只是不會在我們的組織中使用它。然而，他們應該注意確保該 runner 不被他們不認識的其他用戶使用。
|
||||
|
||||
## act runner 支持哪些操作系統？
|
||||
|
||||
它在 Linux、macOS 和 Windows 上運行良好。
|
||||
雖然理論上支持其他操作系統，但它們需要進一步測試。
|
||||
|
||||
需要注意的一點是，如果你選擇直接在主機上運行任務而不是在任務容器中，操作系統之間的環境差異可能會導致意外的失敗。
|
||||
|
||||
例如，bash 在大多數情況下在 Windows 上不可用，而 act 嘗試默認使用 bash 運行腳本。
|
||||
因此，你需要在工作流程文件中指定 `powershell` 為默認 shell，參見 [defaults.run](https://docs.github.com/en/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 系統，還是一個自動化工具。
|
||||
|
||||
開源世界中還實現了許多 [marketplace actions](https://github.com/marketplace?type=actions)。
|
||||
能夠重用它們是令人興奮的。
|
||||
|
||||
## 如果它在多個標籤上運行，例如 `runs-on: [label_a, label_b]` 會怎樣？
|
||||
|
||||
這是有效的語法。
|
||||
這意味著它應該在具有 `label_a` **和** `label_b` 標籤的 runners 上運行，參見 [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`
|
||||
|
||||
我們還需要重新設計任務如何分配給 runners。
|
||||
具有 `ubuntu`、`centos` 或 `with-gpu` 的 runner 並不一定表示它可以接受具有 `[centos, with-gpu]` 的任務。
|
||||
因此，runner 應該通知 Gitea 實例它只能接受具有 `[ubuntu]`、`[centos]`、`[with-gpu]` 和 `[ubuntu, with-gpu]` 的任務。
|
||||
這不是技術問題，只是在早期設計中被忽略了。
|
||||
參見 [runtime.go#L65](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L65)。
|
||||
|
||||
目前，act runner 嘗試匹配標籤中的每個人並使用它找到的第一個匹配。
|
||||
|
||||
## runner 的代理標籤和自定義標籤有什麼區別？
|
||||
|
||||
|
||||
|
||||
代理標籤是在註冊期間由 runner 向 Gitea 實例報告的。
|
||||
另一方面，自定義標籤是由 Gitea 管理員或組織或倉庫的所有者手動添加的（取決於 runner 的級別）。
|
||||
|
||||
然而，這裡的設計需要改進，因為它目前有一些粗糙的邊緣。
|
||||
你可以向已註冊的 runner 添加自定義標籤，例如 `centos`，這意味著 runner 將接收具有 `runs-on: centos` 的任務。
|
||||
然而，runner 可能不知道為這個標籤使用哪個環境，導致它使用默認映像或導致邏輯死胡同。
|
||||
這個默認值可能不符合用戶的期望。
|
||||
參見 [runtime.go#L71](https://gitea.com/gitea/act_runner/src/commit/90b8cc6a7a48f45cc28b5ef9660ebf4061fcb336/runtime/runtime.go#L71)。
|
||||
|
||||
同時，我們建議你重新註冊你的 runner，如果你想更改它的標籤。
|
||||
|
||||
## Gitea Actions runner 會有更多的實現嗎？
|
||||
|
||||
雖然我們希望提供更多選擇，但我們有限的人力意味著 act runner 將是唯一官方支持的 runner。
|
||||
然而，Gitea 和 act runner 都是完全開源的，所以任何人都可以創建一個新的/更好的實現。
|
||||
無論你如何決定，我們都支持你的選擇。
|
||||
如果你 fork 了 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 沒有這樣的引用。
|
||||
> 因此，Gitea Actions 中的 `ref` 是 `refs/pull/:prNumber/head`，它指向 pull request 的 head，而不是合併提交的預覽。
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
date: "2023-04-27T15:00:00+08:00"
|
||||
slug: "overview"
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
Starting with Gitea **1.19**, Gitea Actions are available as a built-in CI/CD solution.
|
||||
|
||||
## Name
|
||||
|
||||
It is similar and compatible to [GitHub Actions](https://github.com/features/actions), and its name is inspired by it too.
|
||||
To avoid confusion, we have clarified the spelling here:
|
||||
|
||||
- "Gitea Actions" (with an "s", both words capitalized) is the name of the Gitea feature.
|
||||
- "GitHub Actions" is the name of the GitHub feature.
|
||||
- "Actions" could refer to either of the above, depending on the context. So it refers to "Gitea Actions" in this document.
|
||||
- "action" or "actions" refer to some scripts/plugins to be used, like "actions/checkout@v4" or "actions/cache@v3".
|
||||
|
||||
## Runners
|
||||
|
||||
Just like other CI/CD solutions, Gitea doesn't run the jobs itself, but delegates the jobs to runners.
|
||||
The runner of Gitea Actions is called [act runner](https://gitea.com/gitea/act_runner), it is a standalone program and also written in Go.
|
||||
It is based on a [fork](https://gitea.com/gitea/act) of [nektos/act](http://github.com/nektos/act).
|
||||
|
||||
Because the runner is deployed independently, there could be potential security issues.
|
||||
To avoid them, please follow two simple rules:
|
||||
|
||||
- Don't use a runner you don't trust for your repository, organization or instance.
|
||||
- Don't provide a runner to a repository, organization or instance you don't trust.
|
||||
|
||||
For Gitea instances used internally, such as instances used by enterprises or individuals, neither of these two rules is a problem, they are naturally so.
|
||||
However, for public Gitea instances, such as [gitea.com](https://gitea.com), these two rules should be kept in mind when adding or using runners.
|
||||
|
||||
## Status
|
||||
|
||||
Gitea Actions is still under development, so there may be some bugs and missing features.
|
||||
And breaking changes may be made before it's stable (v1.20 or later).
|
||||
|
||||
If the situation changes, we will update it here.
|
||||
So please refer to the content here when you find outdated articles elsewhere.
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
date: "2023-04-27T15:00:00+08:00"
|
||||
slug: "quickstart"
|
||||
sidebar_position: 10
|
||||
---
|
||||
|
||||
# Quick Start
|
||||
|
||||
This page will guide you through the process of using Gitea Actions.
|
||||
|
||||
## Set up Gitea
|
||||
|
||||
First of all, you need a Gitea instance.
|
||||
You can follow the [documentation](installation/from-package.md) to set up a new instance or upgrade your existing one.
|
||||
It doesn't matter how you install or run Gitea, as long as its version is 1.19.0 or higher.
|
||||
|
||||
Since 1.21.0, Actions are enabled by default. If you are using versions before 1.21.0, you need to add the following to the configuration file to enable it:
|
||||
|
||||
```ini
|
||||
[actions]
|
||||
ENABLED=true
|
||||
```
|
||||
|
||||
If you want to learn more or encounter any problems while configuring it, please refer to the [Configuration Cheat Sheet](../../administration/config-cheat-sheet.md#actions-actions).
|
||||
|
||||
### Set up runner
|
||||
|
||||
Gitea Actions requires [act runner](https://gitea.com/gitea/act_runner) to run the jobs.
|
||||
In order to avoid consuming too many resources and affecting the Gitea instance, it is recommended to start runners on separate machines from the Gitea instance.
|
||||
|
||||
You can use the [pre-built binaries](http://dl.gitea.com/act_runner) or the [docker images](https://hub.docker.com/r/gitea/act_runner/tags) to set up the runner.
|
||||
|
||||
Before proceeding any further, we suggest running it as a command line with pre-built binaries to ensure that it works with your environment, especially if you are running a runner on your local host.
|
||||
And it could be easier to debug if something goes wrong.
|
||||
|
||||
The runner can run the jobs in isolated Docker containers, so you need to make sure that the Docker has been installed and Docker daemon is running.
|
||||
While it is not strictly necessary, because the runner can also run the jobs directly on the host, it depends on how you configure it.
|
||||
However, it is recommended to use Docker to run the jobs, because it is more secure and easier to manage.
|
||||
|
||||
Before running a runner, you should first register it to your Gitea instance using the following command:
|
||||
|
||||
```bash
|
||||
./act_runner register --no-interactive --instance <instance> --token <token>
|
||||
```
|
||||
|
||||
There are two arguments required, `instance` and `token`.
|
||||
|
||||
`instance` refers to the address of your Gitea instance, like `http://192.168.8.8:3000` or `https://gitea.com`.
|
||||
The runner and job containers (which are started by the runner to execute jobs) will connect to this address.
|
||||
This means that it could be different from the `ROOT_URL` of your Gitea instance, which is configured for web access.
|
||||
It is always a bad idea to use a loopback address such as `127.0.0.1` or `localhost`.
|
||||
If you are unsure which address to use, the LAN address is usually the right choice.
|
||||
|
||||
`token` is used for authentication and identification, such as `P2U1U0oB4XaRCi8azcngmPCLbRpUGapalhmddh23`.
|
||||
Each token can be used to create multiple runners, until it is replaced with a new token using the reset link.
|
||||
You can obtain different levels of 'tokens' from the following places to create the corresponding level of 'runners':
|
||||
|
||||
- Instance level: The admin settings page, like `<your_gitea.com>/admin/actions/runners`.
|
||||
- Organization level: The organization settings page, like `<your_gitea.com>/<org>/settings/actions/runners`.
|
||||
- Repository level: The repository settings page, like `<your_gitea.com>/<owner>/<repo>/settings/actions/runners`.
|
||||
|
||||
|
||||
|
||||
After registering, a new file named `.runner` will appear in the current directory.
|
||||
This file stores the registration information.
|
||||
Please do not edit it manually.
|
||||
If this file is missing or corrupted, you can simply remove it and register again.
|
||||
|
||||
Finally, it's time to start the runner:
|
||||
|
||||
```bash
|
||||
./act_runner daemon
|
||||
```
|
||||
|
||||
And you can see the new runner in the management page:
|
||||
|
||||
|
||||
|
||||
You can find more information by visiting [Act runner](usage/actions/act-runner.md).
|
||||
|
||||
### Use Actions
|
||||
|
||||
Even if Actions is enabled for the Gitea instance, repositories still disable Actions by default.
|
||||
|
||||
To enable it, go to the settings page of your repository like `your_gitea.com/<owner>/repo/settings` and enable `Enable Repository Actions`.
|
||||
|
||||
|
||||
|
||||
The next steps may be rather complicated.
|
||||
You will need to study [the workflow syntax](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) for Actions and write the workflow files you want.
|
||||
|
||||
However, we can just start from a simple demo:
|
||||
|
||||
```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 }}."
|
||||
```
|
||||
|
||||
:::warning
|
||||
|
||||
Certain actions may not function correctly within SHA256 repositories or when Gitea runs on subpath. This includes [actions/checkout](https://github.com/actions/checkout/issues/1843).
|
||||
|
||||
:::
|
||||
|
||||
You can upload it as a file with the extension `.yaml` in the directory `.gitea/workflows/` of the repository, for example `.gitea/workflows/demo.yaml`.
|
||||
You might notice that this is fairly similar from the [Quickstart for GitHub Actions](https://docs.github.com/en/actions/quickstart).
|
||||
That is because Gitea Actions is designed to be compatible with GitHub Actions wherever possible.
|
||||
|
||||
Be careful, the demo file contains some emojis.
|
||||
Please make sure your database supports them, especially when using MySQL.
|
||||
If the charset is not `utf8mb4`, errors will occur, such as `Error 1366 (HY000): Incorrect string value: '\\xF0\\x9F\\x8E\\x89 T...' for column 'name' at row 1`.
|
||||
See [Database Preparation](../../installation/database-preparation.md#mysqlmariadb) for more information.
|
||||
|
||||
Alternatively, you can remove all emojis from the demo file and try again.
|
||||
|
||||
The line `on: [push]` indicates that the workflow will be triggered when you push commits to this repository.
|
||||
However, when you upload the YAML file, it also pushes a commit, so you should see a new task in the Actions tab.
|
||||
|
||||
|
||||
|
||||
Great job! You have successfully started working with Actions.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
date: "2024-07-10T09:23:00+02:00"
|
||||
slug: "secrets"
|
||||
sidebar_position: 50
|
||||
---
|
||||
|
||||
# Secrets
|
||||
|
||||
Secrets allow you to store sensitive information in your user, organization or repository.
|
||||
Secrets are available on Gitea 1.19+ and are only visible in 1.20+ when ACTIONS are enabled.
|
||||
|
||||
# Naming your secrets
|
||||
|
||||
The following rules apply to secret names:
|
||||
|
||||
- Secret names can only contain alphanumeric characters (`[a-z]`, `[A-Z]`, `[0-9]`) or underscores (`_`). Spaces are not allowed.
|
||||
|
||||
- Secret names must not start with the `GITHUB_` and `GITEA_` prefix.
|
||||
|
||||
- Secret names must not start with a number.
|
||||
|
||||
- Secret names are not case-sensitive.
|
||||
|
||||
- Secret names must be unique at the level they are created at.
|
||||
|
||||
For example, a secret created at the repository level must have a unique name in that repository, and a secret created at the organization level must have a unique name at that level.
|
||||
|
||||
### Using secrets
|
||||
|
||||
After creating configuration variables, they will be automatically filled in the `secrets` context.
|
||||
They can be accessed through expressions like `${{ secrets.SECRET_NAME }}` in the workflow.
|
||||
|
||||
### Precedence
|
||||
|
||||
If a secret with the same name exists at multiple levels, the secret at the lowest level takes precedence. For example, if an organization-level secret has the same name as a repository-level secret, then the repository-level secret takes precedence.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
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` 上下文中。
|
||||
可以通過表達式 `${{ vars.VARIABLE_NAME }}` 在工作流程中訪問它們。
|
||||
|
||||
## 優先級
|
||||
|
||||
如果在多個級別存在同名變數，則最低級別的變數優先：
|
||||
倉庫變數將始終優先於組織/用戶變數。
|
||||
Reference in New Issue
Block a user