docs(setup-codex): 重整 action、workflow 與 README 文件

.gitea/workflows/ci.yaml

@@ -35,9 +35,6 @@ jobs:
     runs-on: ubuntu
     # 此 job 專屬的環境變數。
     env:
-      # 版本號規則：固定 0.0.0-beta. 前綴 + Gitea 的執行流水號 run_number，
-      # 讓每次 CI 產生遞增且唯一的 beta 版本字串。
-      VERSION: "0.0.0-beta.${{ gitea.run_number }}"
       # 定義環境變數 IS_BETA：當 PR 的 base 分支為 develop 時為字串 'true'，否則為 'false'；
       # 作為下方 is_beta 輸出的來源，用來決定 test job 是否執行。
       IS_BETA: ${{ gitea.base_ref == 'develop' }}
@@ -48,11 +45,18 @@ jobs:
       is_beta: ${{ env.IS_BETA }}
     # 此 job 的執行步驟。
     steps:
+    - name: Calculate Version
+      id: calculate-version
+      uses: https://gitea.jsc.idv.tw/actions/calculate-version@${{ vars.ACTION_CALCULATE_VERSION }}
+      with:
+        is_beta: ${{ env.IS_BETA }}
     # 步驟：發佈 Release。
     - name: Publishing Release
       # 使用第三方 action 建立 Gitea Release；版本號由 repo variable 控制，
       # 便於集中管理 action 版本、避免硬編碼。
       uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
+      env:
+        VERSION: ${{ steps.calculate-version.outputs.version }}
       # 傳入該 action 的參數。
       with:
         # Release 顯示名稱：「儲存庫名稱 v版本號」。

.gitea/workflows/readme.md

@@ -1,9 +1,86 @@
-# GITEA COMPOSITE ACTION 的工作流列表
+# =============================================================================
+# 用途說明：
+#   這份文件整理 `.gitea/workflows/` 內現有 workflow 與其工作項目，方便人工
+#   快速理解 CI/CD 觸發條件與各 job 的責任分工。
+# 更新日期：2026/07/11 18:39:51 (Asia/Taipei)
+# =============================================================================
 
-- CI
-  - BUILD
-  - TEST
-  - RESULT
-- CD
-  - BUILD
-  - DEPLOY
+## 工作流總覽
+
+| 檔案 | 類型 | 名稱 | 目的 | 觸發條件 |
+| --- | --- | --- | --- | --- |
+| `.gitea/workflows/ci.yaml` | Workflow | `CI` | PR 進入 `master` / `develop` 時跑持續整合，並串接 release、Codex 測試與結果輸出 | `pull_request`，且 base branch 為 `master` 或 `develop`，事件型別為 `opened`、`synchronize` |
+| `.gitea/workflows/master.yaml` | Workflow | `CD` | `master` 分支 push 後，查出對應 commit 所屬 tag 並輸出 | `push` 到 `master` |
+| `.gitea/workflows/readme.md` | 文件 | 目前工作流清單文件 | 列出目前 workflow 與 job 名稱，供人工閱讀 | 無 |
+
+## `.gitea/workflows/ci.yaml`
+
+- Workflow 名稱：`CI`
+- 檔案路徑：`.gitea/workflows/ci.yaml`
+- 目的：
+  - 在 Pull Request 開啟或更新時執行持續整合流程。
+  - 先發佈 Gitea Release，再視條件執行 `setup-codex`，最後輸出 Codex 回覆內容做為流程驗證。
+- 觸發條件：
+  - `pull_request`
+  - 只在 PR base branch 為 `master` 或 `develop` 時觸發
+  - 只在事件型別為 `opened`、`synchronize` 時觸發
+- 主要輸入 / 環境變數：
+  - `env.IS_BETA = ${{ gitea.base_ref == 'develop' }}`
+  - `vars.ACTION_CALCULATE_VERSION`
+  - `vars.ACTION_GITEA_RELEASE_VERSION`
+  - `vars.ACTION_CHECKOUT_VERSION`
+  - `secrets.CODEX_OAUTH`
+  - `gitea.event.repository.name`
+  - `gitea.sha`
+  - `needs.build.outputs.is_beta`
+  - `steps.calculate-version.outputs.version`
+  - `steps.execute.outputs.message`
+- 重要節點：
+  - `build` job 先計算版本，再建立 Release。
+  - `test` job 只在 `is_beta == 'true'` 時執行，也就是 base branch 為 `develop` 的 PR。
+  - `test` job 會使用本 repo 的 composite action `./`，也就是 `setup-codex`。
+  - `test` job 透過 `codex exec "請你進行自我介紹"` 產生多行訊息，寫入 job output。
+  - `result` job 會把 `test` job 的 `message` 印到 log。
+- 備註：
+  - `build` job 與 `test` job 的輸出鏈很依賴 action 版本與 secrets 狀態，若外部 action 版本改變，行為可能跟著變動，需人工確認。
+
+## `.gitea/workflows/master.yaml`
+
+- Workflow 名稱：`CD`
+- 檔案路徑：`.gitea/workflows/master.yaml`
+- 目的：
+  - 在 `master` 分支有 push 時，檢查完整 git 歷史後，以指定 commit 反查對應 tag，並輸出 tag。
+- 觸發條件：
+  - `push`
+  - 只限 `master` 分支
+- 主要輸入 / 環境變數：
+  - `vars.ACTION_CHECKOUT_VERSION`
+  - `env.COMMIT_SHA = ${{ gitea.event.commits[1].id }}`
+  - `GITEA_OUTPUT`
+  - `gitea.event.commits`
+  - `steps.commit.outputs.tag`
+- 重要節點：
+  - `checkout` 使用 `fetch-depth: 0`，以保留完整 tag 歷史，方便 `git describe --contains` 查詢。
+  - `Get Commit Tag` 會把 `git describe --contains` 的結果寫成 step output `tag`。
+  - `Show Tag` 只負責把 tag 印出到 log。
+- 備註：
+  - `COMMIT_SHA` 取的是 `gitea.event.commits[1].id`，不是索引 0。這個寫法代表它預期事件中至少有兩筆 commits，若只有一筆 commit，可能取不到值，需人工確認。
+  - `git describe --contains` 的結果會受 tag 存在與歷史關係影響；若 commit 不在任何 tag 可辨識範圍內，輸出可能不符合預期，需人工確認。
+
+## `.gitea/workflows/readme.md`
+
+- 檔案路徑：`.gitea/workflows/readme.md`
+- 類型：工作流清單文件，不是 workflow
+- 目的：
+  - 目前以簡短清單列出 `CI` 與 `CD`，以及各自的 job 名稱。
+- 觸發條件：
+  - 無，這是文件。
+- 主要輸入 / 環境變數：
+  - 無
+- 重要節點：
+  - 目前內容只列出：
+    - `CI` -> `BUILD`、`TEST`、`RESULT`
+    - `CD` -> `BUILD`、`DEPLOY`
+- 備註：
+  - 這份清單文件與實際 workflow 內容存在落差的可能性，因為 `master.yaml` 目前只看到 `deploy` job，沒有 `BUILD` job；此處需人工確認。
+  - 若要把這份草稿直接覆寫成正式文件，建議先同步確認 workflow 與文件是否一致。