diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index e6d542f..fa52623 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -1,73 +1,139 @@ # -------------------------------------------------- # 用途:定義 CI 工作流程,處理 pull request 的版本發佈與測試。 -# 更新日期:2026/07/11 17:44:33(Asia/Taipei) +# 更新日期:2026/07/11 21:08:44(Asia/Taipei) # -------------------------------------------------- +# 工作流程名稱。 name: CI + +# 定義觸發條件。 on: + # 只在 pull_request 事件上執行,避免其他事件重複觸發。 pull_request: + # 限定 PR 目標分支為 master 與 develop。 branches: + # 正式分支。 - master + # 開發分支。 - develop + # 只在 PR 建立與同步更新時執行。 types: [opened, synchronize] + +# 定義各個 job。 jobs: + # build job 先建立 release,並計算基礎版本資訊。 build: + # 顯示名稱。 name: 1. BUILD + # 使用 Ubuntu runner。 runs-on: ubuntu + # 供此 job 與後續輸出共用的環境變數。 env: + # 預設 beta 版版本字串,使用 run_number 保持唯一。 VERSION: "0.0.0-beta.${{ gitea.run_number }}" + # 只要 PR 的 base branch 是 develop,就視為 beta 流程。 IS_BETA: ${{ gitea.base_ref == 'develop' }} + # 將環境變數輸出到下游 job。 outputs: + # 提供 test job 使用的版本號。 version: ${{ env.VERSION }} + # 提供 test 與 result job 使用的 beta 判斷結果。 is_beta: ${{ env.IS_BETA }} + # 定義 build job 的步驟。 steps: + # 在 Gitea 上建立 release,並讓 tag 與版本對齊。 - name: Publishing Release + # 使用外部 release action,版本由倉庫變數控制。 uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }} with: + # release 名稱包含倉庫名稱與版本號。 name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}" + # tag 名稱固定使用 v 前綴。 tag_name: "v${{ env.VERSION }}" + # 對應到目前提交。 target_commitish: ${{ gitea.sha }} + # beta 分支建立 prerelease,正式分支則不是。 prerelease: ${{ env.IS_BETA }} + + # test job 以 build 輸出為基礎執行版本計算與 beta 專屬檢查。 test: + # 顯示名稱。 name: 2. TEST + # 使用 Ubuntu runner。 runs-on: ubuntu + # 必須等 build 完成,才能取得版本資訊。 needs: [build] + # 將 build 的輸出轉成此 job 的環境變數。 env: + # 取用 build job 輸出的版本。 VERSION: ${{ needs.build.outputs.version }} + # 取用 build job 輸出的 beta 狀態。 IS_BETA: ${{ needs.build.outputs.is_beta }} + # 將 calculate-version 的結果往下輸出。 outputs: + # 最終版本號由 calculate-version step 產生。 version: ${{ steps.calculate-version.outputs.version }} + # 定義 test job 的步驟。 steps: + # 執行 calculate-version action 取得版本號。 - name: Run Calculate Version + # 用 commit 對應版本的動態 action 版本。 id: calculate-version uses: https://gitea.jsc.idv.tw/actions/calculate-version@v${{ env.VERSION }} with: + # 將 beta 狀態轉成布林值傳入 action。 is_beta: ${{ env.IS_BETA == "true" }} + # beta 流程才需要安裝 LLM CLI。 - name: Setup LLM CLI + # 動態指定 setup action 版本。 uses: https://gitea.jsc.idv.tw/actions/setup-${{ vars.ACTION_SETUP_LLM_CLI }} + # 只有 beta 分支才執行。 if: ${{ env.IS_BETA == 'true' }} with: + # 提供 OAuth 憑證給 CLI 安裝流程。 oauth: ${{ secrets.LLM_OAUTH }} + # beta 流程才執行 AI Code Review。 - name: Run AI Code Review + # 用倉庫變數指定 action 版本。 uses: https://gitea.jsc.idv.tw/actions/ai-code-review@${{ vars.ACTION_AI_CODE_REVIEW_VERSION }} + # 步驟 id 供必要時引用輸出。 id: ai-code-review + # 只有 beta 分支才執行。 if: ${{ env.IS_BETA == 'true' }} with: + # 提供 token 給 AI review 流程。 token: ${{ secrets.TOKEN }} + # 指定模型名稱。 model: ${{ vars.LLM_NAME }} + + # result job 只在非 beta 流程時,根據 test 的結果再發佈一次 release。 result: + # 顯示名稱。 name: 3. RESULT + # 使用 Ubuntu runner。 runs-on: ubuntu + # 必須等待 build 與 test 都完成。 needs: [build, test] + # 只有正式版才會進到這個 job。 if: ${{ needs.build.outputs.is_beta == 'false' }} + # 重新帶入版本與 beta 狀態,供 release 步驟使用。 env: + # 取用 test job 算出的版本號。 VERSION: ${{ needs.test.outputs.version }} + # 取用 build job 的 beta 狀態。 IS_BETA: ${{ needs.build.outputs.is_beta }} + # 定義 result job 的步驟。 steps: + # 再次發佈 release,作為正式結果。 - name: Publishing Release + # 與 build job 使用相同的 release action 與版本來源。 uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }} with: + # release 名稱包含倉庫名稱與最終版本號。 name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}" + # 使用與 build 相同的 tag 命名方式。 tag_name: "v${{ env.VERSION }}" + # 指向目前提交。 target_commitish: ${{ gitea.sha }} + # 這裡再次判斷是否為 beta,正式版時會是 false。 prerelease: ${{ env.IS_BETA == "true" }} diff --git a/.gitea/workflows/master.yaml b/.gitea/workflows/master.yaml index 00522ef..7a99856 100644 --- a/.gitea/workflows/master.yaml +++ b/.gitea/workflows/master.yaml @@ -1,28 +1,48 @@ # -------------------------------------------------- -# 用途:定義 CD 工作流程,於 master push 後部署並顯示相關 tag。 -# 更新日期:2026/07/11 17:44:33(Asia/Taipei) +# 用途:定義 CD 工作流程,於 master push 後找出對應 tag 並輸出結果。 +# 更新日期:2026/07/11 21:08:44(Asia/Taipei) # -------------------------------------------------- +# 工作流程名稱。 name: CD + +# 定義觸發條件。 on: + # 只在 push 事件上執行。 push: + # 限定 master 分支,避免其他分支觸發部署流程。 branches: + # 正式分支。 - master + +# 定義部署工作。 jobs: + # deploy job:檢出原始碼並找出 commit 對應的 tag。 deploy: + # 顯示名稱。 name: DEPLOY + # 使用 Ubuntu runner。 runs-on: ubuntu + # 由 push 事件中的 commits 取出要查找的 commit SHA。 env: + # 目前流程預設取第二筆 commit 的 id;此索引是否永遠存在需人工確認。 COMMIT_SHA: ${{ gitea.event.commits[1].id }} + # 定義 deploy job 的步驟。 steps: + # 先檢出完整原始碼與 tag 歷史,讓後續可以查詢 tag。 - name: Source Code Checkout + # 使用 checkout action,版本由倉庫變數控制。 uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }} with: + # 取得完整歷史,避免 tag 查詢因淺層 clone 而失敗。 fetch-depth: 0 + # 根據 COMMIT_SHA 找出包含該提交的最新 tag。 - name: Get Commit Tag + # 將查到的 tag 寫入 Gitea output。 id: commit run: >- echo "tag=$(git for-each-ref --sort=-refname --format='%(refname:strip=2)' refs/tags --contains ${{ env.COMMIT_SHA }} | head -n 1)" >> $GITEA_OUTPUT + # 將查到的 tag 輸出到日誌,方便人工確認。 - name: Show Tag run: >- echo "[DEPLOY][INF][$(TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S')]: ${{ steps.commit.outputs.tag }}" diff --git a/.gitea/workflows/readme.md b/.gitea/workflows/readme.md index 99db59a..7831744 100644 --- a/.gitea/workflows/readme.md +++ b/.gitea/workflows/readme.md @@ -1,6 +1,6 @@ # 工作流程說明 -以下內容整理 `.gitea/workflows/` 目前的工作流程與用途,作為後續覆蓋 `.gitea/workflows/readme.md` 的說明文件。 +以下內容整理 `.gitea/workflows/` 目前的工作流程與用途,作為專案內工作流程的說明文件。 ## 總覽 diff --git a/Dockerfile b/Dockerfile index f2d8aca..389e14b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,15 +1,22 @@ # -------------------------------------------------- -# 用途:定義 calculate-version action 的 Docker 執行環境。 -# 更新日期:2026/07/11 17:44:33(Asia/Taipei) +# 用途:定義 calculate-version action 的 Docker 執行環境與啟動入口。 +# 更新日期:2026/07/11 21:08:44(Asia/Taipei) # -------------------------------------------------- +# 使用 Node LTS Alpine 映像,兼顧 Node 執行環境與較小的映像體積。 FROM node:lts-alpine +# 將工作目錄切換到 /action,後續複製與執行都以此為基準。 WORKDIR /action +# 複製 action 的主程式來源到容器內,供 entrypoint 執行。 COPY src/ /action/src/ + +# 複製 entrypoint 腳本到容器內,作為啟動入口。 COPY entrypoint.sh /action/entrypoint.sh +# 賦予 entrypoint 可執行權限,否則容器啟動時無法直接執行。 RUN chmod +x /action/entrypoint.sh +# 指定容器啟動時直接執行 entrypoint 腳本。 ENTRYPOINT ["/action/entrypoint.sh"] diff --git a/README.md b/README.md index bedaeba..5da3dc7 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # calculate-version -更新時間:2026/07/11 17:53:32(Asia/Taipei) +更新時間:2026/07/11 21:08:44(Asia/Taipei) -這個專案是一個 Gitea Docker action,會讀取 repository 的 release 清單,計算下一個正式版或 beta 版本號,並將結果輸出成 action output。 +這個專案是一個以 Node.js 實作的 Gitea Docker action,負責從 release 清單計算下一個正式版或 beta 版本,並把結果輸出給後續工作流程使用。 ## 專案列表 @@ -10,19 +10,19 @@ | 專案名稱 | 專案描述 | | --- | --- | -| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/) | 這是一個以 Node.js 實作的 Gitea Docker action,提供 release 擷取、版本解析、beta 推算與 action 主流程輸出。 | +| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/) | 這是一個以 Node.js 實作的 Gitea Docker action,負責取得 release 資料、計算下一個版本號,並輸出給 workflow 或 action 使用。 | ### 參考專案表 | 專案名稱 | 參考專案列表 | | --- | --- | -| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/) | 無 | +| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/) | 無 | ### NuGet 套件表 | 專案名稱 | NuGet 套件列表 | | --- | --- | -| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/) | 無 | +| [calculate-version](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/) | 無 | ## 功能列表 @@ -30,21 +30,21 @@ | 功能名稱 | 功能描述 | | --- | --- | -| [calculate-version.normalizeBetaFlag](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L72) | [把空值或 `null` 正規化成 beta 旗標字串](#calculateversionnormalizebetaflag) | -| [calculate-version.parseVersionParts](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L107) | [把版本字串拆成數字片段](#calculateversionparseversionparts) | -| [calculate-version.compareVersionParts](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L125) | [逐段比較版本片段,供排序使用](#calculateversioncompareversionparts) | -| [calculate-version.stableVersionFromTag](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L148) | [解析穩定版 tag 為版本片段](#calculateversionstableversionfromtag) | -| [calculate-version.latestStableVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L169) | [從 release 清單找出最新穩定版](#calculateversionlateststableversion) | -| [calculate-version.nextReleaseVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L195) | [將正式版版本號遞增一版](#calculateversionnextreleaseversion) | -| [calculate-version.nextBetaNumber](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L224) | [推算下一個 beta 編號](#calculateversionnextbetanumber) | -| [calculate-version.calculateVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L252) | [回傳目前最新版本與下一個版本](#calculateversioncalculateversion) | -| [calculate-version.fetchReleases](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L334) | [分頁抓取 repository release 清單](#calculateversionfetchreleases) | -| [calculate-version.main](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/ai-review-resolve/develop-20260711-150530/src/index.js#L373) | [執行 action 主流程並輸出結果](#calculateversionmain) | +| [calculate-version.normalizeBetaFlag](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L95) | [將 beta 輸入正規化成字串 `false`](#calculateversionnormalizebetaflag) | +| [calculate-version.parseVersionParts](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L130) | [將版本字串拆成可比較的數字片段](#calculateversionparseversionparts) | +| [calculate-version.compareVersionParts](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L148) | [比較兩組版本片段的大小](#calculateversioncompareversionparts) | +| [calculate-version.stableVersionFromTag](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L171) | [從 tag 解析穩定版版本片段](#calculateversionstableversionfromtag) | +| [calculate-version.latestStableVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L192) | [找出 release 清單中的最新穩定版](#calculateversionlateststableversion) | +| [calculate-version.nextReleaseVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L218) | [推算下一個正式版版本號](#calculateversionnextreleaseversion) | +| [calculate-version.nextBetaNumber](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L247) | [推算下一個 beta 編號](#calculateversionnextbetanumber) | +| [calculate-version.calculateVersion](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L275) | [依 release 資料與 beta 旗標計算目前版本與下一版](#calculateversioncalculateversion) | +| [calculate-version.fetchReleases](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L357) | [分頁抓取 repository 的 release 清單](#calculateversionfetchreleases) | +| [calculate-version.main](https://gitea.jsc.idv.tw/actions/calculate-version/src/branch/develop/src/index.js#L396) | [執行 action 主流程並輸出版本結果](#calculateversionmain) | ## 使用範例 ### calculate-version.normalizeBetaFlag -把空值、`null` 或未定義值正規化成 `false`,讓後續版本判斷只處理字串。 +將 action 輸入或環境變數轉成固定的字串旗標,避免後續流程混用空值與字串。 ```js const { normalizeBetaFlag } = require('./src/index.js'); @@ -53,7 +53,7 @@ const isBeta = normalizeBetaFlag(process.env.IS_BETA); ``` ### calculate-version.parseVersionParts -將版本字串拆成數字陣列,非數字片段會保守視為 `0`。 +將版本字串拆成數字陣列,適合後續比較或進位運算。 ```js const { parseVersionParts } = require('./src/index.js'); @@ -62,7 +62,7 @@ const parts = parseVersionParts('1.2.3'); ``` ### calculate-version.compareVersionParts -逐段比較兩組版本片段,適合搭配 `Array.prototype.sort()` 使用。 +比較兩組版本片段,常用於排序 release 版本。 ```js const { compareVersionParts } = require('./src/index.js'); @@ -71,7 +71,7 @@ const sorted = [[1, 2, 10], [1, 2, 3]].sort(compareVersionParts); ``` ### calculate-version.stableVersionFromTag -從 tag 名稱擷取穩定版版本資訊,像 `v1.2.3` 會被解析成版本片段。 +從 tag 名稱過濾出穩定版版本,忽略 beta 與不合法格式。 ```js const { stableVersionFromTag } = require('./src/index.js'); @@ -80,7 +80,7 @@ const parts = stableVersionFromTag('v1.2.3'); ``` ### calculate-version.latestStableVersion -從 release 清單中找出最新的穩定版版本號,找不到時回傳 `0.0.0`。 +從 release 清單中找出最新穩定版,若沒有可用資料就回傳 `0.0.0`。 ```js const { latestStableVersion } = require('./src/index.js'); @@ -93,7 +93,7 @@ const latest = latestStableVersion([ ``` ### calculate-version.nextReleaseVersion -將正式版版本號遞增一版,`patch` 與 `minor` 都會以 10 為進位界線。 +將正式版版本號往下一版遞增,patch 會以 10 為進位界線。 ```js const { nextReleaseVersion } = require('./src/index.js'); @@ -114,7 +114,7 @@ const betaNumber = nextBetaNumber([ ``` ### calculate-version.calculateVersion -回傳目前最新版本與下一個版本,beta 模式時會產生對應的 `-beta.N` 結果。 +依 release 資料與 beta 狀態回傳 `[latestVersion, nextVersion]`。 ```js const { calculateVersion } = require('./src/index.js'); @@ -126,7 +126,7 @@ const [latest, nextVersion] = calculateVersion([ ``` ### calculate-version.fetchReleases -分頁抓取 repository 的 release 清單,直到 API 回傳空資料或最後一頁不足頁面上限。 +分頁抓取 repository 的 release 清單,直到 API 沒有新資料為止。 ```js const { fetchReleases } = require('./src/index.js'); @@ -139,7 +139,7 @@ const { fetchReleases } = require('./src/index.js'); ``` ### calculate-version.main -執行 action 主流程,會讀取環境變數、抓取 release、計算版本並輸出結果。 +執行 action 主流程,通常由 Gitea action runtime 觸發。 ```js const { main } = require('./src/index.js'); diff --git a/action.yml b/action.yml index 513435b..41697fa 100644 --- a/action.yml +++ b/action.yml @@ -1,27 +1,54 @@ # -------------------------------------------------- # 用途:宣告 Calculate Version action 的輸入、輸出與 Docker 執行方式。 -# 更新日期:2026/07/11 17:44:33(Asia/Taipei) +# 更新日期:2026/07/11 21:08:44(Asia/Taipei) # -------------------------------------------------- +# action 的顯示名稱。 name: "Calculate Version" + +# action 的簡短描述。 description: "計算版本號" + +# action 的作者資訊。 author: "Jeffery" + +# 宣告可由呼叫端傳入的輸入參數。 inputs: + # 是否以 beta 模式計算版本,預設關閉。 is_beta: + # 參數說明文字。 description: "是否為 beta 版本" + # 未提供時預設為 false,讓一般流程走正式版邏輯。 default: "false" + # 用於讀取 release 資訊的 token,保留為可選輸入。 runner_token: + # 參數說明文字。 description: "用於讀取 release 的 token" + # 明確標示不是必填,呼叫端可依環境提供。 required: false + +# 宣告 action 會輸出的結果欄位。 outputs: + # 將計算後的版本號輸出給後續工作流程使用。 version: + # 輸出說明文字。 description: "計算出的版本號" + +# 指定此 action 以 Docker 模式執行。 runs: + # 透過 Docker image 啟動。 using: "docker" + # 使用同目錄下的 Dockerfile 建置映像。 image: "Dockerfile" + # 將 Gitea 與呼叫端輸入注入容器環境,供 entrypoint 與 Node 程式讀取。 env: + # Gitea 伺服器 URL,供程式組出 API 或資源路徑。 GITEA_SERVER_URL: ${{ gitea.server_url }} + # 目前倉庫識別資訊。 GITEA_REPOSITORY: ${{ gitea.repository }} + # Gitea token,供程式讀取受保護資源。 GITEA_TOKEN: ${{ gitea.token }} + # runner_token 的優先來源是輸入值,其次是 secrets.GITEA_TOKEN,再其次是 secrets.RUNNER_TOKEN。 RUNNER_TOKEN: ${{ inputs.runner_token || secrets.GITEA_TOKEN || secrets.RUNNER_TOKEN }} + # 將呼叫端的 beta 設定直接傳入容器。 IS_BETA: ${{ inputs.is_beta }} diff --git a/entrypoint.sh b/entrypoint.sh index 10ee879..06f0cbb 100755 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -1,9 +1,11 @@ #!/bin/sh # -------------------------------------------------- -# 用途:啟動 calculate-version action,將所有參數交給 Node 主程式。 -# 更新日期:2026/07/11 17:44:33(Asia/Taipei) +# 用途:啟動 calculate-version action,並將所有參數直接轉交給 Node 主程式。 +# 更新日期:2026/07/11 21:08:44(Asia/Taipei) # -------------------------------------------------- +# 啟用嚴格模式,讓未定義變數與任一命令失敗都能立即中止流程。 set -eu +# 直接以 exec 取代 shell 行程,避免多一層 shell 包裝,並把所有參數原封不動傳給 Node。 exec node /action/src/index.js "$@"