# Gitea Workflow 說明文件

更新時間：2026/08/07 13:51:53

## 總覽

此專案（`ai-code-review`）目前包含兩個 workflow：

| Workflow 名稱 | 檔案位置 | 觸發條件 | 大致用途 |
| --- | --- | --- | --- |
| `CI` | `.gitea/workflows/ci.yaml` | `pull_request`（`opened`、`synchronize`） | 計算版本號、必要時建立 release，並在目標分支為 `develop`（beta 情境）時執行 AI 程式碼審查（呼叫本專案自身發佈的 `ai-code-review` action） |
| `CD` | `.gitea/workflows/master.yaml` | `push` 到 `master` 分支 | 輸出完整 Gitea event context，並查詢指定 commit 對應的 tag，作為後續部署流程的基礎資訊 |

以下依 workflow 檔案逐一整理細節。

## Workflow 明細

### CI（`.gitea/workflows/ci.yaml`）

- **workflow 名稱**：`CI`（Gitea UI 顯示標題）
- **檔案位置**：`.gitea/workflows/ci.yaml`
- **用途說明**：
  - `build` job：計算版本號（呼叫 `calculate-version` action），並用計算出的版本建立 Gitea release／tag。
  - `test` job：僅在 `build` job 判定為 beta 情境時執行，呼叫本專案自身發佈的 `ai-code-review` action 對 PR 進行 AI 程式碼審查。
  - `result` job：等待前兩個 job 完成後，將版本號輸出到 log，作為流程結尾的確認步驟。
- **觸發條件**：`pull_request` 事件，且事件類型限定為 `opened` 與 `synchronize`（PR 建立與後續推送同步時觸發）。
- **主要輸入 / 環境參數**：
  - `gitea.base_ref`：用來判斷 PR 目標分支是否為 `develop`，據以設定 `IS_BETA` 環境變數。
  - `vars.ACTION_CALCULATE_VERSION`：`calculate-version` action 的版本（`build` job 使用）。
  - `vars.ACTION_GITEA_RELEASE_VERSION`：`akkuman/gitea-release-action` 的版本（`build` job 使用）。
  - `gitea.event.repository.name`、`gitea.sha`：組成 release 名稱與 `target_commitish`。
  - `needs.build.outputs.version`、`needs.build.outputs.is_beta`：`test`、`result` job 透過 job 輸出取得版本號與 beta 判定結果。
- **重要注意事項**：
  - `test` job 的執行條件為 `needs.build.outputs.is_beta == 'true'`，即 PR 目標分支（`gitea.base_ref`）為 `develop` 時才會執行 AI 程式碼審查。
  - `Publishing Release` 步驟會用 `VERSION` 與 `gitea.sha` 建立對應的 release 與 tag（`v${{ env.VERSION }}`），beta 情境下標記為 prerelease。
  - `test` job 的「Run AI Code Review」步驟在 `ci.yaml` 中本身**未**透過 `with` 或 `env` 傳入任何額外參數；該步驟呼叫的是本專案自身發佈的 `ai-code-review@v{VERSION}` action，實際會用到哪些 `secrets.*`／`vars.*`（例如 action 內部的 token、CLI Proxy 相關設定）屬於該 action 自身的定義範圍，不在 `ci.yaml` 這個 workflow 檔案內顯式宣告，**需人工確認**該 action 版本實際所需的機密與變數是否已在目標環境設定妥當。
  - 若 `vars.ACTION_CALCULATE_VERSION`、`vars.ACTION_GITEA_RELEASE_VERSION` 等變數未設定，對應步驟會失敗，需人工確認部署前置條件是否齊備。

### CD（`.gitea/workflows/master.yaml`）

- **workflow 名稱**：`CD`（Gitea UI 顯示標題）
- **檔案位置**：`.gitea/workflows/master.yaml`
- **用途說明**：單一 `deploy` job，在推送到 `master` 分支後，輸出完整的 Gitea event context，並取回完整原始碼與 tag 歷史後，查詢指定 commit 對應的 tag，將結果印出。整個 workflow 目前僅做資訊輸出與查詢，未包含實際部署動作。
- **觸發條件**：`push` 事件，且限定分支為 `master`。
- **主要輸入 / 環境參數**：
  - `gitea`（整個 context，透過 `toJSON(gitea)` 轉字串）：以 `GITEA_CONTEXT` 環境變數輸出並用 `jq` 顯示。
  - `gitea.event.commits[1].id`：作為 `COMMIT_SHA`，用來查詢該 commit 對應的 tag。
  - `vars.ACTION_CHECKOUT_VERSION`：`actions/checkout` action 的版本。
  - `GITEA_OUTPUT`：`Get Commit Tag` 步驟將 `git describe --contains` 的查詢結果寫入此檔案，供 `steps.commit.outputs.tag` 讀取。
- **重要注意事項**：
  - **需人工確認**：`COMMIT_SHA` 目前固定取用 `gitea.event.commits` 陣列的第 2 筆（索引 1，即 `commits[1]`）。若一次 `push` 事件只包含 1 筆 commit，該索引將不存在，`COMMIT_SHA` 可能為空值，導致後續 `git describe --contains` 查詢失敗或行為不符預期；是否需改為取最後一筆（例如 `commits[-1]` 或依陣列長度動態取值）需人工確認並評估是否調整（本文件僅整理現況，未變更任何 workflow 實際邏輯）。
  - `Get Commit Tag` 步驟依賴完整的 git 歷史與 tag 資訊，因此 `Source Code Checkout` 已設定 `fetch-depth: 0` 與 `fetch-tags: true`，若移除這兩個設定會導致 `git describe --contains` 查不到結果。
  - `Show Gitea Context` 會將完整事件內容輸出到 log，若事件內容包含敏感資訊，需注意執行環境的日誌保存與存取權限策略。

## 備註

- 本文件僅整理 `ci.yaml`、`master.yaml` 兩個 workflow 檔案目前的行為與參數重點，內容依實際檔案內容彙整，未新增或臆測未在檔案中出現的流程與參數；標註「需人工確認」之處為既有設計中需要人工再次確認的風險點，非文件本身待補內容。
- 若後續要以本文件覆蓋既有說明文件，請先確認 `ci.yaml` 與 `master.yaml` 所引用的 `vars.*`、`secrets.*` 已在目標環境（Gitea repo/organization 設定）中正確配置。