docs(README 與文件草稿): 重整說明與草稿內容

2026-07-11 10:00:34 +00:00
parent 1ed40a6b04
commit 24ed2ab164
6 changed files with 407 additions and 14 deletions
@@ -1,9 +1,41 @@
-# GITEA COMPOSITE ACTION 的工作流列表
+# 工作流程說明

- CI
-  - BUILD
-  - TEST
-  - RESULT
- CD
-  - BUILD
-  - DEPLOY
+以下內容整理 `.gitea/workflows/` 目前的工作流程與用途，作為後續覆蓋 `.gitea/workflows/readme.md` 的說明文件。
+
+## 總覽
+
+| Workflow 名稱 | 檔案位置                       | 觸發條件                                                                    | 主要用途                                                           | 相關參數                                                                                                                                                                            |
+| ------------- | ------------------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CI            | `.gitea/workflows/ci.yaml`     | `pull_request` 到 `master` 與 `develop`，事件型別為 `opened`、`synchronize` | 在 PR 階段建立 release、計算版本，beta 分支還會執行 AI code review | `VERSION`、`IS_BETA`、`vars.ACTION_GITEA_RELEASE_VERSION`、`vars.ACTION_SETUP_LLM_CLI`、`vars.ACTION_AI_CODE_REVIEW_VERSION`、`secrets.LLM_OAUTH`、`secrets.TOKEN`、`vars.LLM_NAME` |
+| CD            | `.gitea/workflows/master.yaml` | `push` 到 `master`                                                          | 根據 commit 找出對應 tag，供部署流程或後續檢查使用                 | `COMMIT_SHA`、`vars.ACTION_CHECKOUT_VERSION`                                                                                                                                        |
+
+## CI
+
+- 檔案位置：`.gitea/workflows/ci.yaml`
+- 觸發條件：`pull_request` 到 `master` 與 `develop`，事件型別包含 `opened` 與 `synchronize`
+- 用途說明：先發佈 release 草稿，再呼叫 `calculate-version` action 計算版本；若是 beta 分支，還會設定 LLM CLI 並執行 AI code review。
+- 主要輸入 / 環境參數：
+  - `VERSION`：預設為 `0.0.0-beta.${{ gitea.run_number }}`，供後續 job 使用。
+  - `IS_BETA`：由 `gitea.base_ref == 'develop'` 推得，控制 beta 與正式版流程。
+  - `vars.ACTION_GITEA_RELEASE_VERSION`：`gitea-release-action` 版本。
+  - `vars.ACTION_SETUP_LLM_CLI`：LLM CLI 安裝 action 版本。
+  - `vars.ACTION_AI_CODE_REVIEW_VERSION`：AI code review action 版本。
+  - `secrets.LLM_OAUTH`、`secrets.TOKEN`：beta 流程所需憑證。
+  - `vars.LLM_NAME`：AI code review 使用的模型名稱。
+- 重要注意事項：
+  - `result` job 只在 `IS_BETA == 'false'` 時執行。
+  - `test` job 的 action 來源是 `https://gitea.jsc.idv.tw/actions/calculate-version@v${{ env.VERSION }}`，版本號需與 release 流程對齊。
+  - 若 `develop` 與 `master` 的 release 節奏不同，需確認 `VERSION` 的預設生成邏輯是否符合預期。
+
+## CD
+
+- 檔案位置：`.gitea/workflows/master.yaml`
+- 觸發條件：`push` 到 `master`
+- 用途說明：檢出原始碼後，根據提交 SHA 找出對應 tag，並輸出查得的結果。
+- 主要輸入 / 環境參數：
+  - `COMMIT_SHA`：目前流程中使用 `gitea.event.commits[1].id`，需確認該索引在所有 push 事件下都存在。
+  - `vars.ACTION_CHECKOUT_VERSION`：`actions/checkout` 版本。
+- 重要注意事項：
+  - `fetch-depth: 0` 是必要條件，否則 `git for-each-ref --contains` 可能找不到完整 tag。
+  - `Get Commit Tag` 的 `run` 指令假設 tag 存在；若找不到，輸出會是空字串，需人工確認下游是否能接受。
+  - `Show Tag` 目前採用統一輸出格式草稿，正式實作時仍需確認 shell 內的時間取得方式。