Merge pull request 'feat(ci)：限制 CI 觸發分支並補齊文件' (#12) from ai-review-resolve/develop-20260703-175233 into develop

Reviewed-on: #12

.gitea/workflows/ci.yaml

@@ -1,11 +1,13 @@
 # =============================================================================
 # CI Workflow（Gitea Actions）
 # 用途：在 Pull Request 開啟或更新時觸發的持續整合流程，依序執行三個 job：
-#   1. BUILD  - 發佈 Gitea Release（beta 版本號取自 run_number）。
-#   2. TEST   - checkout 原始碼，執行本 composite action（setup-codex），
-#               再用 codex exec 產生「自我介紹」文字，透過 heredoc 寫入 job output。
+#   1. BUILD  - 發佈 Gitea Release（beta 版本號取自 run_number），並輸出 is_beta。
+#   2. TEST   - 依 BUILD 輸出的 is_beta 決定是否執行；checkout 原始碼，執行本
+#               composite action（setup-codex），再用 codex exec 產生「自我介紹」
+#               文字，透過 heredoc 寫入 job output。
 #   3. RESULT - 顯示 TEST job 輸出的 message，用於驗證整條流程串接成功。
-# 更新日期：2026/07/03 11:41:20
+#   另外，CI 僅在 base 分支為 master 或 develop 的 Pull Request 觸發。
+# 更新日期：2026/07/03 17:56:45
 # =============================================================================
 
 # workflow 名稱，會顯示在 Gitea Actions 的執行清單中。
@@ -14,6 +16,12 @@ name: CI
 on:
   # 監聽 Pull Request 事件。
   pull_request:
+    # 限制只有當 PR 的目標（base）分支為 master 或 develop 時才觸發此 CI。
+    branches:
+    # 納入的目標分支：master。
+    - master
+    # 納入的目標分支：develop。
+    - develop
     # 僅在 PR「開啟」(opened) 或「有新 commit 推送 / 更新」(synchronize) 時觸發，
     # 避免 closed / reopened 等其他事件也啟動整條 CI。
     types: [opened, synchronize]
@@ -30,7 +38,13 @@ jobs:
       # 版本號規則：固定 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' }}
+    # 定義此 job 對外輸出，供後續 job（test）取用其判斷結果。
     outputs:
+      # 將環境變數 IS_BETA 暴露為 job 層級的 is_beta 輸出；當 PR base 分支為 develop 時為 'true'，
+      # 供 test job 以 `if ... == 'true'` 判斷是否執行（即：僅 develop 的 PR 會跑 test）。
       is_beta: ${{ env.IS_BETA }}
     # 此 job 的執行步驟。
     steps:
@@ -49,7 +63,7 @@ jobs:
         target_commitish: ${{ gitea.sha }}
         # 是否標記為「預發佈」(prerelease)：當 PR 目標分支 base_ref 為 develop 時為 true，
         # 代表流向 develop 的變更視為預發佈版本。
-        prerelease: ${{ gitea.base_ref == 'develop' }}
+        prerelease: ${{ env.IS_BETA }}
   # ---- Job 2：TEST（執行 setup-codex 並產生自我介紹）----
   test:
     # job 顯示名稱。
@@ -58,7 +72,9 @@ jobs:
     runs-on: ubuntu
     # 相依關係：需等 build job 成功後才執行。
     needs: [build]
-    if: ${{ needs.build.outputs.is_beta }}
+    # 執行條件：僅當 build job 的 is_beta 輸出等於字串 'true' 時才執行本 test job；
+    # 否則整個 test job 會被略過。
+    if: ${{ needs.build.outputs.is_beta == 'true' }}
     # 定義此 job 對外輸出，供後續 job（result）取用。
     outputs:
       # 將名為 execute 的步驟輸出的 message，暴露為 job 層級的 message 輸出。

.gitea/workflows/master.yaml

@@ -3,7 +3,7 @@
 #   本 workflow 為「CD（持續部署）」流程，於程式碼 push 到 master 分支時觸發。
 #   主要工作為 checkout 完整原始碼、依指定 commit 反查其所屬的 git tag，
 #   並將該 tag 輸出顯示，供後續部署或版本追蹤使用。
-# 更新日期：2026/07/03 11:41:20 (Asia/Taipei)
+# 更新日期：2026/07/03 17:43:30 (Asia/Taipei)
 # =============================================================================
 
 # workflow 名稱，顯示於 Gitea Actions 介面
@@ -36,6 +36,7 @@ jobs:
     - name: Source Code Checkout
       # 使用 actions/checkout，版本由 repo/organization 變數 ACTION_CHECKOUT_VERSION 決定
       uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
+      # with：傳入 checkout action 的參數區塊
       with:
         # fetch-depth: 0 代表抓取完整 git 歷史（含所有 tag），
         # 以利後續 git describe 能正確反查 tag（淺層 clone 會導致查不到）。

README.md

@@ -1,6 +1,6 @@
 # setup-codex
 
-> 更新時間：2026/07/03 11:45:51
+> 更新時間：2026/07/03 17:56:45
 
 `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 的公開程式方法**。
 
@@ -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（PR 發佈 Release + 執行 action）與 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 驗證檔完成登入，並顯示目前登入帳號；另附 CI（僅在 base 為 master／develop 的 PR 觸發，發佈 Release、依 is_beta 決定是否執行 codex 測試）與 CD（push master 反查 commit tag）示範 workflow。 |
 
 ### 參考專案
 
@@ -69,5 +69,7 @@ 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) | Pull Request `opened`／`synchronize` | 發佈 beta Release、執行本 action 並以 `codex exec` 產生自我介紹、顯示結果。 |
+| [.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 11:41:20
+# 更新日期：2026/07/03 17:33:39
 # =============================================================================
 
 # action 名稱：顯示於 Gitea/GitHub Actions UI 上的識別名稱