diff --git a/.gitea/ai-review/findings.json b/.gitea/ai-review/findings.json index 7fad757..fe51488 100644 --- a/.gitea/ai-review/findings.json +++ b/.gitea/ai-review/findings.json @@ -1,41 +1 @@ -[ - { - "level": "warning", - "role": "Bard", - "location": "action.yml:1", - "problem": "檔案頭部充斥著過度冗長、瑣碎且描述基礎 YAML 語法的註解，破壞了設定檔應有的簡潔層次，且增加了維護負擔。", - "suggestion": "建議大幅精簡檔案頭部註解，僅保留必要的業務邏輯摘要，移除過細的步驟解說與基礎語法定義。" - }, - { - "level": "warning", - "role": "Leo", - "location": "action.yml:25", - "problem": "參數 `files` 的 `description` 為空，使得呼叫方在查閱使用說明時缺乏必要的上下文，未來維護者也難以快速掌握此參數的具體用途。", - "suggestion": "補上具體說明，例如 `description: '要釋出的成品檔案路徑或 glob'`。", - "is_new": true - }, - { - "level": "warning", - "role": "Mage", - "location": "action.yml:47", - "problem": "Step 2 將 version_value 直接寫入 GITHUB_OUTPUT 而未進行格式驗證。若上游 calculate-version 輸出的內容包含換行符或其他特殊字元，可能會導致 GITHUB_OUTPUT 格式損壞，甚至產生環境變數注入風險。", - "suggestion": "在寫入 GITHUB_OUTPUT 前，應使用 regex 驗證 version_value 是否符合預期的版本號格式（例如僅包含數字與點號）。", - "is_new": true - }, - { - "level": "warning", - "role": "Mage", - "location": "action.yml:107", - "problem": "Step 4 直接使用 gitea.ref 作為 target_commitish。若此 Action 被 Tag 事件觸發，gitea.ref 可能為 refs/tags/...，這在某些 Gitea release 工具中可能無法正確對應到 Commit，導致發布失敗。", - "suggestion": "建議將 target_commitish 改為使用 ${{ gitea.sha }}，以確保 Release 錨定在正確的 Commit SHA 上，避免因 Ref 格式問題導致執行失敗。", - "is_new": true - }, - { - "level": "info", - "role": "Bard", - "location": "action.yml:43", - "problem": "檔案中充斥著過度細節的區塊註解（例如 Step 1, Step 2...），對於熟悉 YAML 與 Actions 的開發者而言，這些註解顯得冗餘且干擾了閱讀的流暢節奏。", - "suggestion": "移除這些描述顯而易見行為的步驟區塊註解，讓程式碼結構一目瞭然，僅在 shell 腳本的複雜邏輯處加入關鍵註解即可。", - "is_new": true - } -] +[] diff --git a/README.md b/README.md index 4177d95..763c2e1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Release Tag Version -更新時間：2026/06/26 10:47:20 +更新時間：2026/06/26 10:56:00 本專案為 Gitea Actions 的 **composite action**，用來自動計算版本號、建立 release 並標註對應 tag，最後清理舊成品。 @@ -43,6 +43,8 @@ steps: with: # files 為非必填；指定要隨 release 一起釋出（上傳）的成品檔案，可省略。 files: dist/* + # is_debug 為非必填；設為 true 時，會轉傳給 calculate-version 產生測試標籤版本。 + is_debug: 'false' ``` ### 本 repo 內的 CD workflow（`.gitea/workflows/cd.yaml`） @@ -68,7 +70,7 @@ jobs: 引用後，composite action 會依序執行： -1. **版本號計算**：呼叫 `docker-actions/calculate-version` 算出本次版本號。 +1. **版本號計算**：呼叫 `docker-actions/calculate-version` 算出本次版本號，並轉傳 `is_debug` 以支援測試標籤版本。 2. **組合釋出參數**：版本號非空時，組出 release 的 `name`（格式 ` v<版本>`）與 `tag_name`（格式 `v<版本>`）。 3. **檢查版本號輸出**：版本號為空時輸出錯誤訊息並 `exit 1`，中止流程，避免建立錯誤的 release/tag。 4. **釋出並標註成品版本**：以 `akkuman/gitea-release-action` 建立 release 並打 tag，附帶 `files` 指定的成品。 @@ -78,4 +80,4 @@ jobs: - 變數 `vars.ACTION_CALCULATE_VERSION`、`vars.ACTION_GITEA_RELEASE_VERSION`、`vars.ACTION_RELEASE_CLEANUP_VERSION`、`vars.ACTION_CHECKOUT_VERSION` 皆需設定且值有效。 - runner 需有 `ubuntu` label。 -- 預期結果：在 Gitea 上建立 `v<版本>` 的 release 與 tag，並清理舊成品。 +- 預期結果：在 Gitea 上建立 `v<版本>` 的 release 與 tag；`is_debug` 為 `true` 時使用測試標籤版本，最後清理舊成品。 diff --git a/action.yml b/action.yml index f1777fa..a1479fc 100644 --- a/action.yml +++ b/action.yml @@ -1,122 +1,58 @@ -# ============================================================================= -# 指令檔用途： -# 這是一個 Gitea composite action（複合動作），名稱為「Release Tag Version」。 -# 它被其他 workflow 引用，用來「自動計算版本號並釋出（release）標註成品版本」。 -# 完整流程： -# (1) 呼叫 calculate-version action 計算本次的版本號。 -# (2) 若版本號非空，組合 release 所需的 name 與 tag_name。 -# (3) 若版本號為空，輸出錯誤訊息並以 exit 1 中止整個 action。 -# (4) 呼叫 akkuman/gitea-release-action 在 Gitea 上建立 release 並打 tag， -# 同時可附帶要釋出的檔案（files）。 -# (5) 呼叫 release-cleanup action 清理舊的成品（release）。 -# -# 更新日期：2026/06/26 10:14:14（Asia/Taipei） -# ============================================================================= +# Release Tag Version：計算版本號、建立 Gitea release/tag，並清理舊成品。 +# 更新日期：2026/06/26 11:10:00（Asia/Taipei） -# action 的顯示名稱，會在 Gitea Actions 介面與被引用時呈現。 name: 'Release Tag Version' -# action 的說明文字，描述此 action 的目的：釋出並標註成品版本。 description: '釋出並標註成品版本' -# action 作者標註，僅作為 metadata，不影響執行行為。 author: 'Jeffery' -# inputs 區塊：定義此 composite action 對外開放、可由呼叫方傳入的參數。 inputs: - # files 參數：指定要隨 release 一起釋出（上傳）的檔案。 files: - # 此參數的描述（原始檔留空）。 - # 需人工確認：description 為空字串，建議補上說明（例如「要釋出的成品檔案路徑或 glob」）以利維護， - # 但屬文件性質、不影響執行邏輯，故此處不逕自修改。 - description: '' - # required: false 表示此參數非必填；呼叫方未傳入時，files 會是空值。 + description: '要釋出的成品檔案路徑或 glob' required: false + is_debug: + description: '是否產生測試標籤版本' + required: false + default: 'false' -# runs 區塊：定義此 action 的執行方式與步驟。 runs: - # using: 'composite' 表示這是「複合動作」，由下方多個 step 串接組成，而非單一 Docker/JS action。 using: 'composite' - # steps：依序執行的步驟清單，順序具有意義，不可調換。 steps: - # --------------------------------------------------------------------------- - # Step 1：版本號計算 - # 引用外部 calculate-version action 來計算本次要釋出的版本號， - # 其結果會以 output「version」提供給後續步驟（透過 step id 取用）。 - # --------------------------------------------------------------------------- - name: 版本號計算 - # id 設為 version-calculate，後續步驟以 steps.version-calculate.outputs.version 取得計算結果。 - id: version-calculate - # uses：引用 Gitea 上 docker-actions/calculate-version action。 - # 版本（@ 後面）由 repository/organization 變數 vars.ACTION_CALCULATE_VERSION 決定， - # 便於集中管理被引用 action 的版本，不需改動本檔。 + id: calculate-version uses: https://gitea.jsc.idv.tw/docker-actions/calculate-version@${{ vars.ACTION_CALCULATE_VERSION }} - - # --------------------------------------------------------------------------- - # Step 2：組合釋出參數 - # 僅在版本號非空時執行，組出 release 需要的 name 與 tag_name， - # 並寫入 GITHUB_OUTPUT 供後續釋出步驟取用。 - # --------------------------------------------------------------------------- - - name: 組合釋出參數 - # id 設為 release-params，後續步驟以 steps.release-params.outputs.* 取得組好的 name / tag_name。 - id: release-params - # if 條件：只有當上一步算出的 version 不是空字串時才執行此步驟。 - # 這是「版本有效」的分支，與 Step 3「版本為空」的分支互斥。 - if: ${{ steps.version-calculate.outputs.version != '' }} - # run：以 shell 執行下列指令來組合參數。 - run: | - # 取得目前 repository 完整名稱（格式為 owner/repo），存入 repository 變數。 - repository="${{ gitea.repository }}" - # 取得 Step 1 計算出的版本號，存入 version_value 變數。 - version_value="${{ steps.version-calculate.outputs.version }}" - # 組出 release 的顯示名稱並寫入 GITHUB_OUTPUT： - # ${repository##*/} 為 bash 參數展開，去掉最長前綴「*/」，即取 owner/repo 的最後一段 repo 名稱。 - # 最終格式為「 v<版本>」（注意 v 前有一個空白）。 - echo "name=${repository##*/} v${version_value}" >> "$GITHUB_OUTPUT" - # 組出 release 的 tag 名稱並寫入 GITHUB_OUTPUT：格式為「v<版本>」（v 緊接版本，無空白）。 - echo "tag_name=v${version_value}" >> "$GITHUB_OUTPUT" - # shell: bash 明確指定以 bash 執行（${repository##*/} 等參數展開語法需 bash 支援）。 - shell: bash - - # --------------------------------------------------------------------------- - # Step 3：檢查版本號輸出 - # 僅在版本號為空時執行；視為錯誤狀況，輸出訊息到 stderr 並中止 action。 - # --------------------------------------------------------------------------- - - name: 檢查版本號輸出 - # if 條件：只有當 version 為空字串時才執行；與 Step 2 的條件互斥，為「版本無效」分支。 - if: ${{ steps.version-calculate.outputs.version == '' }} - # run：輸出錯誤訊息並以非零結束碼中止流程。 - run: | - # 將錯誤訊息寫到 stderr（>&2），表示 calculate-version 沒有產出有效版本號。 - echo "version-calculate output version is empty" >&2 - # 以 exit 1 結束此步驟並讓整個 action 失敗，避免後續用空版本去建立錯誤的 release/tag。 - exit 1 - # shell: bash 明確指定以 bash 執行此步驟。 - shell: bash - - # --------------------------------------------------------------------------- - # Step 4：釋出並標註成品版本 - # 引用 akkuman/gitea-release-action，在 Gitea 上建立 release 並打 tag。 - # 依賴 Step 2 組好的 name / tag_name；若 Step 3 已 exit 1，本步驟不會執行。 - # --------------------------------------------------------------------------- - - name: 釋出並標註成品版本 - # uses：引用第三方 akkuman/gitea-release-action，負責實際的 release 建立與 tag 標註。 - # 版本由 vars.ACTION_GITEA_RELEASE_VERSION 控制，集中管理被引用版本。 - uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }} - # with：傳入 release action 所需的參數。 with: - # name：release 的顯示名稱，來自 Step 2 組出的 outputs.name（格式「 v<版本>」）。 + is_debug: ${{ inputs.is_debug }} + + - name: 組合釋出參數 + id: release-params + if: ${{ steps.calculate-version.outputs.version != '' }} + run: | + repository="${{ gitea.repository }}" + version_value="${{ steps.calculate-version.outputs.version }}" + + if [[ ! "$version_value" =~ ^[0-9]+(\.[0-9]+)*([._-][0-9A-Za-z]+)*$ ]]; then + echo "version-calculate output version has invalid format: ${version_value}" >&2 + exit 1 + fi + + echo "name=${repository##*/} v${version_value}" >> "$GITHUB_OUTPUT" + echo "tag_name=v${version_value}" >> "$GITHUB_OUTPUT" + shell: bash + + - name: 檢查版本號輸出 + if: ${{ steps.calculate-version.outputs.version == '' }} + run: | + echo "version-calculate output version is empty" >&2 + exit 1 + shell: bash + + - name: 釋出並標註成品版本 + uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }} + with: name: ${{ steps.release-params.outputs.name }} - # tag_name：release 對應的 tag 名稱，來自 Step 2 組出的 outputs.tag_name（格式「v<版本>」）。 tag_name: ${{ steps.release-params.outputs.tag_name }} - # target_commitish：release/tag 要指向的 ref（分支或 commit），這裡使用觸發此次執行的 gitea.ref。 - target_commitish: ${{ gitea.ref }} - # files：要附加到 release 的成品檔案，來自本 action 的 inputs.files（呼叫方傳入，可為空）。 + target_commitish: ${{ gitea.sha }} files: ${{ inputs.files }} - # --------------------------------------------------------------------------- - # Step 5：清理舊成品 - # 引用 release-cleanup action，清理過舊的 release/成品，避免無限累積。 - # --------------------------------------------------------------------------- - name: 清理舊成品 - # uses：引用 Gitea 上 docker-actions/release-cleanup action 執行清理。 - # 版本由 vars.ACTION_RELEASE_CLEANUP_VERSION 控制。 uses: https://gitea.jsc.idv.tw/docker-actions/release-cleanup@${{ vars.ACTION_RELEASE_CLEANUP_VERSION }}