From 18b226906ff58d6e2228e2119273c6cbdcc26f8f Mon Sep 17 00:00:00 2001 From: Jeffery Date: Sat, 11 Jul 2026 10:44:30 +0000 Subject: [PATCH] =?UTF-8?q?docs(setup-codex):=20=E9=87=8D=E6=95=B4=20actio?= =?UTF-8?q?n=E3=80=81workflow=20=E8=88=87=20README=20=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/ci.yaml | 10 ++-- .gitea/workflows/readme.md | 93 ++++++++++++++++++++++++++++++++++---- README.md | 33 ++++++-------- action.yml | 2 +- 4 files changed, 107 insertions(+), 31 deletions(-) diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index 91c15a8..839c7aa 100644 --- a/.gitea/workflows/ci.yaml +++ b/.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版本號」。 diff --git a/.gitea/workflows/readme.md b/.gitea/workflows/readme.md index fd64672..ca3bbf0 100644 --- a/.gitea/workflows/readme.md +++ b/.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 \ No newline at end of file +## 工作流總覽 + +| 檔案 | 類型 | 名稱 | 目的 | 觸發條件 | +| --- | --- | --- | --- | --- | +| `.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 與文件是否一致。 diff --git a/README.md b/README.md index 1dffd5d..ba1b544 100644 --- a/README.md +++ b/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 - uses: actions/checkout@v4 - # 引用本 repo 根目錄的 composite action - - name: Run Setup Codex - uses: ./ - with: - oauth: ${{ secrets.CODEX_OAUTH }} - # 登入完成後即可直接呼叫 codex - - name: Execute Codex - shell: bash - run: codex exec "請你進行自我介紹" + - name: Source Code Checkout + uses: actions/checkout@v4 + - name: Run Setup Codex + uses: ./ + with: + oauth: ${{ secrets.CODEX_OAUTH }} + - name: Execute Codex + 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 可能取不到值。 diff --git a/action.yml b/action.yml index 94ba427..cd4e5e0 100644 --- a/action.yml +++ b/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 上的識別名稱