# GITEA 工作流說明

## 總覽

目前專案內有 2 條 workflow 與 1 份 workflow README 文件：

| Workflow 名稱 | 檔案位置 | 觸發條件 | 用途 |
| --- | --- | --- | --- |
| CI | `.gitea/workflows/ci.yaml` | `pull_request` 到 `master`、`develop`，事件類型為 `opened`、`synchronize` | 在 PR 階段建立版本、發佈 release，並在 beta 情境下執行工具鏈與清理動作 |
| CD | `.gitea/workflows/master.yaml` | `push` 到 `master` | 在主分支推送後取得 commit tag，作為部署或版本追蹤依據 |
| WORKFLOW README | `.gitea/workflows/readme.md` | 文件檔，無觸發條件 | 整理 workflow 名稱、觸發條件與注意事項，方便維護與查閱 |

## CI

- 檔案位置：`.gitea/workflows/ci.yaml`
- 用途：在 pull request 階段先建立版本、發佈 release，並在 beta 情境下執行後續工具鏈與清理動作。
- 觸發條件：PR 指向 `master` 或 `develop`，且事件為 `opened` 或 `synchronize`。
- 主要參數：
  - `vars.ACTION_CALCULATE_VERSION`：版本計算 action 版本。
  - `vars.ACTION_GITEA_RELEASE_VERSION`：release action 版本。
  - `vars.ACTION_SETUP_LLM_CLI`：LLM CLI 設定 action 名稱或版本識別。
  - `vars.ACTION_AI_CODE_REVIEW_VERSION`：AI code review action 版本。
  - `vars.LLM_NAME`：模型名稱。
  - `secrets.LLM_OAUTH`：LLM CLI OAuth 憑證。
  - `secrets.TOKEN`：Gitea API token。
  - `gitea.run_number`、`gitea.base_ref`、`gitea.sha`：版本號、beta 判斷與 release target commit。
- 重要注意事項：
  - `build` job 先計算版本，再發佈 release；`Publishing Release` 這個 step 的 `env.VERSION` 是否能被後續表達式正確使用，需人工確認。
  - `test` job 目前有 `outputs.message` 指向 `steps.docker-template.outputs.message`，但現有 steps 中沒有 `docker-template` step，這一點需人工確認。
  - `Run Cleanup Release` 目前使用 `env.VERSION` 組 action 版本字串，實際是否與預期發布版本一致，需人工確認。
  - `result` job 只輸出版本號，不再輸出訊息內容，與舊版流程不同。

## CD

- 檔案位置：`.gitea/workflows/master.yaml`
- 用途：在 `master` 分支推送後 checkout 原始碼並顯示對應 commit tag。
- 觸發條件：`push` 到 `master`。
- 主要參數：
  - `vars.ACTION_CHECKOUT_VERSION`：checkout action 版本。
  - `gitea.event.commits[1].id`：用於 `git describe --contains` 的 commit SHA。
  - `GITEA_OUTPUT`：job step 輸出檔案。
- 重要注意事項：
  - `gitea.event.commits[1]` 的索引是否一定存在，需人工確認，避免 push 內容少於兩筆 commit 時出錯。
  - `fetch-depth: 0` 是為了讓 `git describe` 能讀取完整歷史，不能省略。

## readme

- 檔案位置：`.gitea/workflows/readme.md`
- 用途：整理 workflow 名稱、觸發條件與注意事項，方便快速查閱。
- 觸發條件：無，這是文件檔。
- 主要參數：無。
- 重要注意事項：此文件不改動任何 workflow 設定，只負責說明與彙整。