Merge pull request 'docs(setup-codex): 重整 action、workflow 與 README 文件' (#13) from develop into master

Reviewed-on: #13

.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
+| `.gitea/workflows/ci.yaml` | Workflow | `CI` | PR 進入 `master` / `develop` 時跑持續整合，並串接 release、Codex 測試與結果輸出 | `pull_request`，且 base branch 為 `master` 或 `develop`，事件型別為 `opened`、`synchronize` |
-  - BUILD
+| `.gitea/workflows/master.yaml` | Workflow | `CD` | `master` 分支 push 後，查出對應 commit 所屬 tag 並輸出 | `push` 到 `master` |
-  - DEPLOY
+| `.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 與文件是否一致。

README.md

@@ -1,8 +1,8 @@
 # setup-codex
 
-> 更新時間：2026/07/03 17:56:45
+> 更新時間：2026/07/11 18:39:51（Asia/Taipei）
 
-`setup-codex` 是一個 **Gitea composite action**，用於在 Gitea Actions runner 上安裝並登入 [Codex CLI](https://chatgpt.com/codex)，讓後續 workflow 步驟能直接呼叫已完成 OAuth 登入的 `codex` 指令。本 repo 由 action 定義（`action.yml`）與示範用的 CI／CD workflow 組成，內容皆為 YAML 與少量 shell／Node，**不含可列入 README 的公開程式方法**。
+`setup-codex` 是一個 **Gitea composite action**，用於在 Gitea Actions runner 上安裝並登入 [Codex CLI](https://chatgpt.com/codex)，讓後續 workflow 步驟能直接呼叫已完成 OAuth 登入的 `codex` 指令。本 repo 由 action 定義（`action.yml`）與示範用的 CI／CD workflow 組成，內容皆為 YAML 與少量 shell／Node。
 
 ## 專案列表
 
@@ -10,7 +10,7 @@
 
 | 專案名稱 | 專案描述 |
 | --- | --- |
-| [setup-codex](https://gitea.jsc.idv.tw/actions/setup-codex/src/branch/develop) | Gitea composite action：安裝 Codex CLI、以 base64 編碼的 OAuth 驗證檔完成登入，並顯示目前登入帳號；另附 CI（僅在 base 為 master／develop 的 PR 觸發，發佈 Release、依 is_beta 決定是否執行 codex 測試）與 CD（push master 反查 commit tag）示範 workflow。 |
+| [setup-codex](https://gitea.jsc.idv.tw/actions/setup-codex/src/branch/develop) | Gitea composite action：安裝 Codex CLI、以 base64 編碼的 OAuth 驗證檔完成登入，並透過 workflow 範例展示如何在 CI／CD 中串接 Codex。 |
 
 ### 參考專案
 
@@ -26,7 +26,7 @@
 
 ## 功能列表
 
-本專案為 Gitea composite action（YAML + shell／Node），未公開任何可列入 README 的程式方法（public method／constructor／extension method／operator）。
+本專案未公開可列入 README 的功能（public method／constructor／extension method／operator）。
 
 | 功能名稱 | 功能描述 |
 | --- | --- |
@@ -34,8 +34,6 @@
 
 ## 使用範例
 
-> 說明：本專案無公開程式方法，以下改以「如何在 workflow 中使用此 composite action」作為使用範例。
-
 ### 在 workflow 中引用 action
 
 在同一個 repo 內，可用相對路徑 `./` 引用本 action；跨 repo 則以 `owner/repo@版本` 引用。此 action 需要一個必填參數 `oauth`（透過 OAuth 登入 ChatGPT 產生、並經 base64 編碼的驗證檔內容，建議存放於 secrets）。
@@ -45,17 +43,15 @@ jobs:
   demo:
     runs-on: ubuntu
     steps:
-    - name: Source Code Checkout
+      - name: Source Code Checkout
-      uses: actions/checkout@v4
+        uses: actions/checkout@v4
-    # 引用本 repo 根目錄的 composite action
+      - name: Run Setup Codex
-    - name: Run Setup Codex
+        uses: ./
-      uses: ./
+        with:
-      with:
+          oauth: ${{ secrets.CODEX_OAUTH }}
-        oauth: ${{ secrets.CODEX_OAUTH }}
+      - name: Execute Codex
-    # 登入完成後即可直接呼叫 codex
+        shell: bash
-    - name: Execute Codex
+        run: codex exec "請你進行自我介紹"
-      shell: bash
-      run: codex exec "請你進行自我介紹"
 ```
 
 **前置條件與注意事項**
@@ -63,6 +59,7 @@ jobs:
 - `oauth`：必填。內容為 Codex／ChatGPT OAuth 驗證檔（`auth.json`）先經 base64 編碼後的字串，請存於 secret（例如 `CODEX_OAUTH`）避免外洩。
 - action 會在 runner 家目錄產生 `~/.codex/auth.json`（含機敏憑證），並將 Codex 執行檔目錄加入 `PATH`。
 - action 內建的 `Show Codex Account` 步驟會將登入帳號的 email 輸出到 workflow log，請留意 log 的存取權限與隱私。
+- `outputs.message` 目前參照的 `steps.exchange` 步驟不存在，屬於既有問題，需人工確認。
 
 ### 對應的 workflow 檔案
 
@@ -71,5 +68,3 @@ jobs:
 | [action.yml](https://gitea.jsc.idv.tw/actions/setup-codex/src/branch/develop/action.yml) | 被其他 workflow 以 `uses` 引用 | 定義安裝／登入 Codex 的 composite action。 |
 | [.gitea/workflows/ci.yaml](https://gitea.jsc.idv.tw/actions/setup-codex/src/branch/develop/.gitea/workflows/ci.yaml) | base 為 `master`／`develop` 的 Pull Request（`opened`／`synchronize`） | 發佈 beta Release；`build` 依 `base_ref == 'develop'` 設定 `IS_BETA` 並輸出 `is_beta`，當 `is_beta == 'true'`（即 develop 的 PR）時執行本 action 以 `codex exec` 產生自我介紹、顯示結果。 |
 | [.gitea/workflows/master.yaml](https://gitea.jsc.idv.tw/actions/setup-codex/src/branch/develop/.gitea/workflows/master.yaml) | push 至 `master` | 反查指定 commit 所屬的 git tag 並顯示。 |
-
-> ⚠️ 注意（既有、待人工確認）：`action.yml` 的 `outputs.message` 參照的 `steps.exchange` 步驟不存在，該 output 可能取不到值。

action.yml

@@ -5,7 +5,7 @@
 #     2) 使用外部傳入、經 base64 編碼的 OAuth 驗證檔完成 Codex 登入。
 #     3) 解析登入驗證檔中的 id_token，輸出目前登入的帳號 email 以供確認。
 #   使用情境：讓後續 workflow 步驟可直接呼叫已登入的 Codex CLI。
-# 更新日期：2026/07/03 17:33:39
+# 更新日期：2026/07/11 18:39:51
 # =============================================================================
 
 # action 名稱：顯示於 Gitea/GitHub Actions UI 上的識別名稱