From 5058a5dd4ae75f9b78c141679f49466f567953d6 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 30 Jun 2026 12:13:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(README=20=E8=88=87=20CD=20workflow):=20?= =?UTF-8?q?=E9=87=8D=E5=BB=BA=20README=20=E4=B8=A6=E7=82=BA=20cd.yaml=20?= =?UTF-8?q?=E8=A3=9C=E9=80=90=E8=A1=8C=E8=A8=BB=E8=A7=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/cd.yaml | 48 ++++++++++++++++++++++++ README.md | 80 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) diff --git a/.gitea/workflows/cd.yaml b/.gitea/workflows/cd.yaml index 1249810..ebd54c7 100644 --- a/.gitea/workflows/cd.yaml +++ b/.gitea/workflows/cd.yaml @@ -1,35 +1,83 @@ +# ============================================================================= +# 用途：這是 Gitea Actions 的 CD（持續部署）workflow。 +# 當有 commit push 到 master 分支時觸發，流程分兩個 job 依序執行： +# 1. release-tag-version：釋出並標註成品版本，取得版本號。 +# 2. docker-build-push：依上一步取得的版本號 docker build 映像檔， +# 並 push 到 gitea.jsc.idv.tw 倉庫。 +# 更新日期：2026/06/30 12:00:23 +# ============================================================================= + +# workflow 名稱，會顯示在 Gitea Actions 介面上，方便辨識此流程 name: CD +# 觸發條件區塊，定義哪些事件會啟動此 workflow on: + # 監聽 push 事件（有提交被推送到倉庫時） push: + # 限定只有 push 到下列分支時才觸發，避免其他分支誤觸發部署 branches: + # 僅針對 master 分支（正式主線）觸發 CD - master +# 工作（job）區塊，定義此 workflow 包含的所有 job jobs: + # 第一個 job：負責釋出並標註成品版本，產出版本號供後續 job 使用 release-tag-version: + # job 的顯示名稱，呈現在 Actions 介面 name: Release Tag Version + # 指定執行此 job 的 runner 標籤（自架的 ubuntu runner） runs-on: ubuntu + # 定義此 job 對外輸出的值，供其他 job 透過 needs 引用 outputs: + # 將下方 id 為 release-tag-version 的 step 所輸出的 version + # 暴露為此 job 的 version 輸出，後續 docker-build-push 會用到 version: ${{ steps.release-tag-version.outputs.version }} + # 此 job 的執行步驟清單 steps: + # 步驟：執行外部 composite action 來釋出並標註成品版本 - name: 釋出並標註成品版本 + # 設定 step 的 id，讓 outputs 能以 steps.release-tag-version 引用其輸出 id: release-tag-version + # 使用 Gitea 上的共用 composite action 取得版本號； + # 版本以變數 vars.ACTION_RELEASE_TAG_VERSION 釘選，便於統一管理 action 版本 uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }} + # 第二個 job：建置 Docker 映像檔並推送到倉庫 docker-build-push: + # job 的顯示名稱 name: Docker Build & Push + # 指定執行此 job 的 runner 標籤（自架的 ubuntu runner） runs-on: ubuntu + # 宣告此 job 相依於 release-tag-version； + # 確保版本號先產生完成才執行，並可透過 needs 取得其 outputs needs: release-tag-version + # 此 job 範圍內的環境變數，供下方 steps 的 run 指令使用 env: + # 目標倉庫主機（Gitea container registry 位址） SERVER: gitea.jsc.idv.tw + # 登入倉庫所使用的帳號 USERNAME: jiantw83 + # 登入倉庫所使用的密碼／權杖，從 Gitea secrets 取得，避免明文外洩 PASSWORD: ${{ secrets.TOKEN }} + # 此 job 的執行步驟清單 steps: + # 步驟：取出原始碼到 runner 工作目錄，後續 docker build 需要 Dockerfile 等檔案 - name: 取得存取庫 + # 使用官方 checkout action；版本以變數 vars.ACTION_CHECKOUT_VERSION 釘選 uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }} + # 步驟：登入 Docker 倉庫，取得推送映像檔的權限 - name: 登入倉庫 + # 將密碼透過管線餵給 docker login 的 --password-stdin，避免密碼出現在指令參數中 run: echo $PASSWORD | docker login $SERVER -u $USERNAME --password-stdin + # 指定以 bash 執行此指令 shell: bash + # 步驟：建置 Docker 映像檔 - name: 建置映像檔 + # 以倉庫名稱（gitea.repository）為 image 名稱、上一個 job 產生的 version 為 tag， + # 對當前目錄（.）的 Dockerfile 進行 build run: docker build -t $SERVER/${{ gitea.repository }}:${{ needs.release-tag-version.outputs.version }} . + # 指定以 bash 執行此指令 shell: bash + # 步驟：將建置完成的映像檔推送到倉庫 - name: 推送映像檔 + # push 與上一步相同名稱與 tag 的映像檔到 SERVER 指定的倉庫 run: docker push $SERVER/${{ gitea.repository }}:${{ needs.release-tag-version.outputs.version }} + # 指定以 bash 執行此指令 shell: bash diff --git a/README.md b/README.md index e69de29..7177b48 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,80 @@ +# codex + +> 更新時間（Asia/Taipei）：2026/06/30 12:04:48 + +以多階段建置（multi-stage build）打包 [@openai/codex](https://www.npmjs.com/package/@openai/codex) CLI 的 Docker 映像檔專案。build 階段於 `node:<版本>-slim` 透過 npm 全域安裝 codex CLI，runtime 階段改用同樣精簡的 `node-slim` 基底，只帶入 codex 套件與其相依，並額外安裝 `ca-certificates` 以支援 HTTPS 連線，最終映像預設執行 `codex --version`。搭配 `.gitea/workflows/cd.yaml`，當 push 到 `master` 分支時，會自動釋出版本號、建置映像檔並推送到 Gitea 倉庫。 + +## 專案列表 + +### 專案描述 + +| 專案名稱 | 專案描述 | +| --- | --- | +| [codex](https://gitea.jsc.idv.tw/images/codex/src/branch/develop) | 以多階段建置打包 @openai/codex CLI 的 Docker 映像檔專案，提供 `Dockerfile` 與 Gitea Actions CD 流程；此專案未公開可列入 README 的功能。 | + +### 參考專案 + +| 專案名稱 | 參考專案列表 | +| --- | --- | +| [codex](https://gitea.jsc.idv.tw/images/codex/src/branch/develop) | 無 | + +### NuGet 套件 + +| 專案名稱 | NuGet 套件列表 | +| --- | --- | +| [codex](https://gitea.jsc.idv.tw/images/codex/src/branch/develop) | 無 | + +## 功能列表 + +本專案為 Docker 映像檔建置專案，未公開可列入 README 的程式方法（public method／constructor／extension method／operator）。實際交付內容為下列容器映像檔的建置與發佈設定，使用方式詳見「使用範例」。 + +## 使用範例 + +### 建置映像檔 + +於專案根目錄（含 `Dockerfile`）執行： + +```bash +docker build -t codex . +``` + +- 預設使用 `node:22-slim` 作為 build 與 runtime 基底，並全域安裝 `@openai/codex`。 +- 建議啟用 BuildKit（檔首已宣告 `# syntax=docker/dockerfile:1`）：`DOCKER_BUILDKIT=1 docker build -t codex .`。 + +### 執行容器 + +```bash +# 顯示 codex 版本（映像檔預設 CMD） +docker run --rm codex + +# 覆寫預設指令，改執行其他 codex 子指令 +docker run --rm codex codex --help +``` + +### 以 build 參數覆寫預設值 + +`Dockerfile` 將可調參數集中於檔首 `ARG`，可於建置時覆寫： + +```bash +# 指定 node 版本 +docker build --build-arg NODE_VERSION=20 -t codex:node20 . + +# 指定要安裝的 npm 套件（預設 @openai/codex） +docker build --build-arg CODEX_PACKAGE=@openai/codex@latest -t codex:latest . +``` + +| 參數 | 預設值 | 說明 | +| --- | --- | --- | +| `NODE_VERSION` | `22` | node 基底映像版本（同時套用於 build 與 runtime 階段） | +| `BUILD_IMAGE` | `node:${NODE_VERSION}-slim` | build 階段基底映像 | +| `RUNTIME_IMAGE` | `node:${NODE_VERSION}-slim` | runtime 階段基底映像 | +| `CODEX_PACKAGE` | `@openai/codex` | 要全域安裝的 npm 套件名稱 | + +### CI/CD 自動發佈（Gitea Actions） + +`.gitea/workflows/cd.yaml` 定義 CD 流程：當 push 到 `master` 分支時觸發，依序執行兩個 job： + +1. **Release Tag Version**：以共用 composite action 釋出並標註成品版本，輸出 `version`。 +2. **Docker Build & Push**：checkout 原始碼 → 登入 `gitea.jsc.idv.tw` 倉庫（帳密來自 secrets）→ 以 `gitea.repository` 為映像名稱、上一步 `version` 為 tag 建置並推送映像檔。 + +> 對外契約（CI 倉庫位址 `gitea.jsc.idv.tw`、登入帳號、`secrets.TOKEN`、建置與推送指令）皆沿用原設定，未變更。