refresh review pipeline

.gitea/workflows/ci.yaml

@@ -1,5 +1,7 @@
-# 用途：CI workflow 的 command-file 草稿，保留原始流程並補上逐行說明。
-# 更新時間：2026/07/11 19:00:45
+# ============================================================================
+# 用途：這是 pull request 時計算版本、視情況發佈 release、並在目標分支為 develop 的 beta 情境下執行 AI Code Review 的 CI workflow。
+# 更新時間：2026/08/07 13:51:53
+# ============================================================================
 # workflow 名稱，對應 Gitea UI 中的顯示標題。
 name: CI
 # 定義此 workflow 的觸發事件。

.gitea/workflows/master.yaml

@@ -1,5 +1,7 @@
-# 用途：master workflow 的 command-file 草稿，保留原始流程並補上逐行說明。
-# 更新時間：2026/07/11 19:00:45
+# ============================================================================
+# 用途：推送到 master 分支後，輸出 Gitea context、查詢 commit 對應 tag，作為部署前資訊檢查的 CD workflow
+# 更新時間：2026/08/07 13:51:53
+# ============================================================================
 # workflow 名稱，對應 Gitea UI 中的顯示標題。
 name: CD
 # 定義此 workflow 的觸發事件。

.gitea/workflows/readme.md

@@ -1,49 +1,58 @@
-# GITEA NODE ACTION 工作流說明草稿
+# Gitea Workflow 說明文件
 
-更新時間：2026/07/11 18:54:51
+更新時間：2026/08/07 13:51:53
 
 ## 總覽
 
-此專案目前包含兩個 workflow：
+此專案（`ai-code-review`）目前包含兩個 workflow：
 
-- `CI`：處理 pull request 期間的版本計算、釋出與 AI 程式碼審查。
-- `CD`：處理推送到 `master` 分支後的部署相關檢查與資訊輸出。
+| 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
+### CI（`.gitea/workflows/ci.yaml`）
 
-- 檔案位置：`.gitea/workflows/ci.yaml`
-- 用途：在 pull request 事件中計算版本，必要時建立 release，並在 beta 情境下執行 AI 程式碼審查。
-- 觸發條件：`pull_request`，事件類型為 `opened` 與 `synchronize`。
-- 主要輸入 / 環境參數：
-  - `gitea.base_ref`：用來判斷是否為 `develop`，進而決定 `IS_BETA`。
-  - `vars.ACTION_CALCULATE_VERSION`：提供 `calculate-version` action 的版本。
-  - `vars.ACTION_GITEA_RELEASE_VERSION`：提供 release action 的版本。
-  - `secrets.LLM_OAUTH`：設定 LLM CLI 的 OAuth。
-  - `secrets.TOKEN`：提供 AI 程式碼審查 action 存取 Gitea API。
-  - `vars.LLM_NAME`：指定審查使用的模型名稱。
-- 重要注意事項：
-  - `test` job 只會在 `IS_BETA == true` 時執行，也就是 pull request 目標分支為 `develop` 時。
-  - `Publishing Release` 會使用 `VERSION` 與 `gitea.sha` 建立 release 與 tag。
-  - 若變數或 secret 未設定，對應步驟會失敗，需人工確認部署前置條件。
+- **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
+### CD（`.gitea/workflows/master.yaml`）
 
-- 檔案位置：`.gitea/workflows/master.yaml`
-- 用途：在 `master` 分支推送後輸出 Gitea context、檢查提交標籤，作為後續部署流程的基礎。
-- 觸發條件：`push` 到 `master` 分支。
-- 主要輸入 / 環境參數：
-  - `gitea` 事件內容：轉成 `GITEA_CONTEXT` 後交給 `jq` 顯示。
-  - `gitea.event.commits[1].id`：作為 `COMMIT_SHA`，用來查詢 commit tag。
-  - `vars.ACTION_CHECKOUT_VERSION`：提供 `actions/checkout` 的版本。
-  - `GITEA_OUTPUT`：寫入 `git describe --contains` 的結果。
-- 重要注意事項：
-  - `COMMIT_SHA` 取用 commits 陣列的第 2 筆資料，若 push 事件實際只有 1 筆 commit，需人工確認是否會發生索引風險。
-  - `Get Commit Tag` 依賴完整的 git 歷史與 tags，因此 checkout 已設定 `fetch-depth: 0` 與 `fetch-tags: true`。
-  - `Show Gitea Context` 會輸出完整事件內容，若包含敏感資訊，需注意執行環境的日誌保存策略。
+- **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，若事件內容包含敏感資訊，需注意執行環境的日誌保存與存取權限策略。
 
 ## 備註
 
-- 本檔為草稿版本，僅整理 workflow 行為與設定重點，不修改任何 workflow 實際邏輯。
-- 若後續要覆蓋正式檔，請先確認 `ci.yaml` 與 `master.yaml` 的變數與 secret 已在目標環境中正確配置。
+- 本文件僅整理 `ci.yaml`、`master.yaml` 兩個 workflow 檔案目前的行為與參數重點，內容依實際檔案內容彙整，未新增或臆測未在檔案中出現的流程與參數；標註「需人工確認」之處為既有設計中需要人工再次確認的風險點，非文件本身待補內容。
+- 若後續要以本文件覆蓋既有說明文件，請先確認 `ci.yaml` 與 `master.yaml` 所引用的 `vars.*`、`secrets.*` 已在目標環境（Gitea repo/organization 設定）中正確配置。