diff --git a/.gitea/workflows/readme.md b/.gitea/workflows/readme.md index ca3bbf0..12ce827 100644 --- a/.gitea/workflows/readme.md +++ b/.gitea/workflows/readme.md @@ -1,86 +1,42 @@ -# ============================================================================= -# 用途說明： -# 這份文件整理 `.gitea/workflows/` 內現有 workflow 與其工作項目，方便人工 -# 快速理解 CI/CD 觸發條件與各 job 的責任分工。 -# 更新日期：2026/07/11 18:39:51 (Asia/Taipei) -# ============================================================================= +# setup-codex 工作流說明 + +本專案已改用共用工作流：共同的 CI / CD 流程由 `actions/composite-template` 的 `.gitea/scoped_workflows/`（Gitea scoped workflows 機制）自動套用到本 repo 執行，**不在本目錄內**。本目錄只保留 setup-codex 專屬的自測工作流，與共用流程並行執行。 ## 工作流總覽 -| 檔案 | 類型 | 名稱 | 目的 | 觸發條件 | -| --- | --- | --- | --- | --- | -| `.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 名稱，供人工閱讀 | 無 | +| 檔案 | 名稱 | 觸發條件 | 目的 | +| --- | --- | --- | --- | +| （共用）`composite-template/.gitea/scoped_workflows/ci.yaml` | `CI` | `pull_request`（`opened`、`synchronize`；目標分支 `master` / `develop`） | 版本計算、release 發佈、AI Code Review、舊 release 清理 | +| （共用）`composite-template/.gitea/scoped_workflows/master.yaml` | `CD` | `push` 到 `master` | 反查本次合併對應的 release tag | +| `.gitea/workflows/ci.yaml` | `CI`（自測） | `pull_request`（`opened`、`synchronize`；目標分支 `master` / `develop`），僅 base 為 `develop` 時執行 | 以本 repo 的 composite action 安裝 codex CLI 並實測 | + +共用工作流的細節與 vars / secrets 需求，請見 `composite-template/.gitea/scoped_workflows/readme.md`。 ## `.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 版本改變，行為可能跟著變動，需人工確認。 +### Job：TEST — 安裝並實測 codex CLI（`if: gitea.base_ref == 'develop'`） -## `.gitea/workflows/master.yaml` +| 步驟 | 目的 | +| --- | --- | +| `Source Code Checkout` | 取出原始碼，讓 `uses: ./` 能找到本 repo 的 composite action | +| `Run Setup Codex` | 執行本 repo 根目錄的 composite action（即 setup-codex 自身），以 OAuth 憑證完成 codex CLI 安裝與認證 | +| `Execute Codex` | 執行 `codex exec "請你進行自我介紹"`，將多行回覆以 heredoc 寫入 step output `message`，驗證 CLI 可用 | -- 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 可辨識範圍內，輸出可能不符合預期，需人工確認。 +### Job：RESULT — 輸出 codex 回覆 -## `.gitea/workflows/readme.md` +| 步驟 | 目的 | +| --- | --- | +| `Show Message` | 將 TEST 輸出的 `message` 印到執行紀錄，確認輸出鏈串接成功（此步驟例外以 step 層 `env` 中轉，因 message 為多行且可能含特殊字元） | -- 檔案路徑：`.gitea/workflows/readme.md` -- 類型：工作流清單文件，不是 workflow -- 目的： - - 目前以簡短清單列出 `CI` 與 `CD`，以及各自的 job 名稱。 -- 觸發條件： - - 無，這是文件。 -- 主要輸入 / 環境變數： - - 無 -- 重要節點： - - 目前內容只列出： - - `CI` -> `BUILD`、`TEST`、`RESULT` - - `CD` -> `BUILD`、`DEPLOY` -- 備註： - - 這份清單文件與實際 workflow 內容存在落差的可能性，因為 `master.yaml` 目前只看到 `deploy` job，沒有 `BUILD` job；此處需人工確認。 - - 若要把這份草稿直接覆寫成正式文件，建議先同步確認 workflow 與文件是否一致。 +### 參數 + +| 參數 | 優先權鏈 | 說明 | +| --- | --- | --- | +| 是否執行自測 | `gitea.base_ref == 'develop'` | 比照共用 CI 的 beta 判斷，僅 develop 的 PR 執行 | +| checkout 版本 | `vars.ACTION_CHECKOUT_VERSION` | 指定 `actions/checkout` 的 tag（組織層級已設定） | +| `oauth` | `secrets.CODEX_OAUTH` | codex CLI 的 OAuth 憑證（本 repo 專屬 secret，必須設定） | + +## 備註 + +- 原本的 CI / CD 工作流（版本計算、release 發佈、AI Code Review、tag 反查）已刪除，其功能完全由共用工作流覆蓋；目前的 `ci.yaml` 是內容不同的自測流程，請勿在本目錄重新加入與共用流程重複的步驟，否則同一事件會重複執行（重複發 release、重複 AI review）。 +- 自測與共用 CI 是兩條獨立的 workflow run，且顯示名稱同為 `CI`（Gitea 以檔案路徑識別，名稱重複不衝突；可由 job 組成區分——共用版為 `BUILD / TEST / RESULT`，自測只有 `TEST / RESULT`）。自測失敗不會擋下共用 CI 的 release 發佈，合併前請同時確認兩者的執行結果。