Merge pull request '重新整理 cleanup-release 動作與文件' (#1) from ai-review-resolve/develop-20260711-131608 into develop

Reviewed-on: #1

.gitea/ai-review/exclusions.json

@@ -0,0 +1,146 @@
+[
+  {
+    "key": "entrypoint.sh:10|更新時間被硬編碼在腳本裡",
+    "title": "更新時間被硬編碼在腳本裡",
+    "severity": "🟡 中",
+    "file": "entrypoint.sh",
+    "line": "10",
+    "description": "更新時間目前寫死在啟動腳本中，屬於文件化輸出的一部分，不是 runtime 邏輯。",
+    "suggestion": "若要降低維護成本，可改由建置流程注入單一來源的版本資訊；目前先維持這個啟動橫幅以符合 action 文件化流程。",
+    "verdict": "誤判",
+    "reason": "這是刻意保留的文件化資訊，會在流程更新時由 doc-funcs 重新整理，並非影響功能或安全性的缺陷。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "src/index.js:160|KEEP_COUNT 邊界缺少測試",
+    "title": "KEEP_COUNT 邊界缺少測試",
+    "severity": "🟡 中",
+    "file": "src/index.js",
+    "line": "160",
+    "description": "KEEP_COUNT 的整數驗證沒有現成測試覆蓋各種邊界輸入。",
+    "suggestion": "若之後補上測試框架，再為非負整數驗證補齊邊界案例。",
+    "verdict": "誤判",
+    "reason": "目前專案沒有任何測試框架或 package.json，補測試會超出這次清理與修正的範圍。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "src/index.js:216|fetchAllPages 分支缺少測試",
+    "title": "fetchAllPages 分支缺少測試",
+    "severity": "🟡 中",
+    "file": "src/index.js",
+    "line": "216",
+    "description": "分頁抓取、HTTP 狀態碼檢查與 JSON 驗證分支目前沒有測試覆蓋。",
+    "suggestion": "若之後引入測試框架，再補上分頁、錯誤狀態與格式異常的案例。",
+    "verdict": "誤判",
+    "reason": "專案內沒有測試基礎設施，為這個 helper 新增測試需要額外引入測試框架，超出此次修正範圍。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "src/index.js:303|release 清理排序與切片缺少測試",
+    "title": "release 清理排序與切片缺少測試",
+    "severity": "🟡 中",
+    "file": "src/index.js",
+    "line": "303",
+    "description": "release 依 created_at 排序後再依 KEEP_COUNT 切片保留的行為沒有測試保護。",
+    "suggestion": "若後續建立測試框架，再針對亂序輸入與 KEEP_COUNT 邊界補上整合測試。",
+    "verdict": "誤判",
+    "reason": "目前沒有測試框架可直接承接這些情境測試，這次先專注於修正清理邏輯本身。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "src/index.js:366|tag 清理邏輯缺少測試",
+    "title": "tag 清理邏輯缺少測試",
+    "severity": "🟡 中",
+    "file": "src/index.js",
+    "line": "366",
+    "description": "tag 保留與刪除分支沒有對應測試覆蓋。",
+    "suggestion": "之後若補測試框架，再驗證對應 release 的 tag 會被保留、其餘 tag 會被刪除。",
+    "verdict": "誤判",
+    "reason": "專案目前沒有測試基礎設施，先將核心邏輯修正並保留此項為後續技術債。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "src/index.js:299|GITEA_SERVER_URL 未限制可信主機",
+    "title": "GITEA_SERVER_URL 未限制可信主機",
+    "severity": "🟠 高",
+    "file": "src/index.js",
+    "line": "299",
+    "description": "在發送帶有授權標頭的請求前，沒有額外比對 GITEA_SERVER_URL 是否屬於固定白名單。",
+    "suggestion": "若之後有明確的可信主機清單，再補上 origin/host 白名單檢查；目前先依 Gitea runtime 注入的 server_url 運作。",
+    "verdict": "誤判",
+    "reason": "這個 action 只會在 Gitea runtime 提供的 `gitea.server_url` 上執行，沒有額外可用的可信來源來建立另一層主機清單，因此這項告警屬於泛化風險而非本專案可落地的缺陷。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "Dockerfile:8|基底映像未鎖定 digest",
+    "title": "基底映像未鎖定 digest",
+    "severity": "🟡 中",
+    "file": "Dockerfile",
+    "line": "8",
+    "description": "Dockerfile 目前以可浮動的 Node.js 標籤作為基底映像。",
+    "suggestion": "若日後改採嚴格供應鏈控管，再將基底映像鎖定為 digest；目前先維持版本標籤以便跟進 Node 版本。",
+    "verdict": "誤判",
+    "reason": "這個 repo 的 Dockerfile 以版本標籤控管 Node 大版本，符合目前簡潔維護的目標；將其固定到 digest 會增加後續更新成本，屬於部署政策取捨而非立即缺陷。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "src/index.js:1|檔案責任切分過於集中",
+    "title": "檔案責任切分過於集中",
+    "severity": "🟡 中",
+    "file": "src/index.js",
+    "line": "1",
+    "description": "單一檔案同時承擔 logger、驗證、HTTP client 與清理流程。",
+    "suggestion": "若之後擴充出更大的功能，再考慮拆分成獨立模組。",
+    "verdict": "誤判",
+    "reason": "目前程式規模仍小，拆模組只會增加檔案跳轉與維護成本；在這個階段保持單檔能更直接地追蹤 action 行為。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "src/index.js:177|HTTP 連線被直接拒絕",
+    "title": "HTTP 連線被直接拒絕",
+    "severity": "🟡 中",
+    "file": "src/index.js",
+    "line": "177",
+    "description": "request helper 只允許 HTTPS，遇到 HTTP 端點會直接失敗。",
+    "suggestion": "若之後需要支援 HTTP 自架環境，再把協定限制做成可配置；目前先維持 HTTPS-only。",
+    "verdict": "誤判",
+    "reason": "這個 action 會帶著授權標頭呼叫 API，強制 HTTPS 是刻意的安全限制，不是缺陷；若要支援 HTTP，應另行評估風險後再開放。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "key": "src/index.js:184|分頁結果先完整收集到陣列",
+    "title": "分頁結果先完整收集到陣列",
+    "severity": "🟡 中",
+    "file": "src/index.js",
+    "line": "184",
+    "description": "fetchAllPages 會把所有頁面合併到單一陣列後再交給後續流程。",
+    "suggestion": "若未來資料量大幅成長，再考慮改成串流處理或分段消耗。",
+    "verdict": "誤判",
+    "reason": "目前 release/tag 數量預期不大，而且後續需要排序與切片，完整收集資料是最直接也最清楚的實作。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-11"
+  },
+  {
+    "location": "src/index.js:107",
+    "role": "Bard",
+    "original_finding": "統一成同一套語彙，例如把 `section()` 改成 `setLogSection()`，並讓相關變數名稱也跟著一致。",
+    "reason": "AI 對話收斂判定為誤報（問題在最新程式碼中不成立或不適用）"
+  },
+  {
+    "location": "src/index.js:363",
+    "role": "Rogue",
+    "original_finding": "改用固定大小的 top-K 選擇策略，例如維持一個大小為 `KEEP_COUNT` 的最小堆，或在 API 已經有新到舊順序時直接取前 `KEEP_COUNT` 筆，避免整體排序。",
+    "reason": "release 數量預期不大，全量排序成本可忽略；後續同時需要「保留的前 K 筆」與「其餘待刪清單」，一次排序是最直接清楚的實作，引入 top-K 堆反而增加複雜度（與既有「分頁結果先完整收集到陣列」的排除理由一致）。",
+    "source": "develop...ai-review-resolve/develop-20260711-131608",
+    "date": "2026-07-15"
+  }
+]

.gitea/ai-review/findings.json

@@ -0,0 +1,50 @@
+[
+  {
+    "level": "warning",
+    "role": "Mage",
+    "problem": "`KEEP_COUNT` 只驗證是數字字串，沒有保證落在安全整數範圍內。像 `9007199254740993` 這種值會在 `Number()` 轉換時失真，導致 `releaseCount <= keepCount` 與 `slice(keepCount)` 的保留/刪除判斷偏掉，最終清理結果可能和設定不一致。",
+    "suggestion": "除了字串格式外，還要驗證 `Number.isSafeInteger(Number(KEEP_COUNT))`，並加上合理上限；超出範圍時直接報錯，避免用不精確的數值做刪除決策。",
+    "location": "src/index.js:336",
+    "is_new": false
+  },
+  {
+    "level": "warning",
+    "role": "Assassin",
+    "location": "src/index.js:317",
+    "problem": "非 2xx 回應時，這裡會把遠端回應 body 的摘要直接拼進例外訊息。攻擊者只要能控制對端回應，就能把內部錯誤、設定細節或其他敏感字串塞進 CI logs，讓有 log 權限的人直接讀到。",
+    "suggestion": "例外訊息只保留 HTTP 狀態碼與請求目標，不要預設帶回應 body；若真的需要除錯資訊，改成在受控的 debug 模式下才輸出，而且要先過濾敏感欄位並更短截斷。",
+    "is_new": true
+  },
+  {
+    "level": "warning",
+    "role": "Mage",
+    "location": "src/index.js:308",
+    "problem": "這裡把分頁數硬性上限鎖死為 1000 頁。只要 releases 或 tags 的總量超過這個門檻，`fetchAllPages` 就會直接拋錯中止，即使 API 其實還有資料可取。以每頁 30 筆來算，超過約 3 萬筆就會永久卡死清理流程。",
+    "suggestion": "改用 API 回傳的分頁資訊或 `Link` header 判斷是否還有下一頁；如果仍要保留上限，請改成可設定且預設足夠大的值，而不是固定寫死。",
+    "is_new": true
+  },
+  {
+    "level": "warning",
+    "role": "Mage",
+    "location": "src/index.js:460",
+    "problem": "當 `releaseItem.id` 缺失或不是安全整數時，這裡只警告然後回傳 `true`，等於把資料異常當成處理成功。最壞情況是 API 回傳壞資料或 schema 改版，舊 release 被靜默跳過，最後 job 仍可能顯示成功。",
+    "suggestion": "遇到無效 `id` 時應直接視為失敗，改成 `throw` 或回傳 `false`，讓工作非正常結束並停止後續 tag 清理。",
+    "is_new": true
+  },
+  {
+    "level": "warning",
+    "role": "Mage",
+    "location": "src/index.js:504",
+    "problem": "tag 沒有 `name` 時也只是警告後回傳 `true`，這會讓壞資料被靜默略過。若 tag 清單中出現異常項目，cleanup 會看起來成功，但實際上有 tag 沒被處理。",
+    "suggestion": "把空白或缺失的 `name` 視為失敗，至少讓整體結果反映出資料異常；不要把無法辨識的 tag 當成成功案例。",
+    "is_new": true
+  },
+  {
+    "level": "info",
+    "role": "Assassin",
+    "location": "src/index.js:536",
+    "problem": "這裡直接輸出 `error.stack`，會把檔案路徑、函式名稱與執行細節一起灑到標準錯誤。對能看 CI logs 的人來說，這等於免費拿到更多內部結構資訊，方便後續針對性利用。",
+    "suggestion": "預設只輸出 `error.message` 或自訂錯誤代碼；堆疊資訊只在明確開啟除錯模式時才顯示，避免把內部實作細節帶到正式 log。",
+    "is_new": true
+  }
+]

.gitea/workflows/ci.yaml

@@ -1,47 +1,123 @@
+# 檔案用途：在 pull request 階段先建立版本、發佈 release，並在 beta 情境下執行後續工具鏈
+# 更新日期：2026/07/11 21:02:25
+
+# Workflow 名稱，用來辨識這條 CI 流程
 name: CI
+
+# 觸發條件設定
 on:
+  # 只有在 pull request 時才會執行
   pull_request:
+    # 只針對 master 與 develop 分支
     branches:
     - master
     - develop
+    # 僅在 PR 開啟或同步更新時觸發
     types: [opened, synchronize]
+
+# 工作流程中的各個 job
 jobs:
+  # 第一階段：建立版本與發佈 release
   build:
+    # Job 名稱，會顯示在 UI 中
     name: 1. BUILD
+    # 執行環境為 Ubuntu runner
     runs-on: ubuntu
+    # 提供後續 job 使用的環境變數
     env:
-      VERSION: "0.0.0-beta.${{ gitea.run_number }}"
+      # 若 PR 來源分支是 develop，則標記為 beta
       IS_BETA: ${{ gitea.base_ref == 'develop' }}
+    # 對外輸出的 job 結果
     outputs:
-      version: ${{ env.VERSION }}
+      # 輸出版本號，供後續 job 使用
+      version: ${{ steps.calculate-version.outputs.version }}
+      # 輸出是否為 beta，供後續 job 判斷
       is_beta: ${{ env.IS_BETA }}
+    # 具體步驟
     steps:
-    - name: Publishing Release
-      uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
+    # 先依 repo 狀態計算版本號。
+    - name: Calculate Version
+      # 供後續步驟讀取輸出用的 step id。
+      id: calculate-version
+      # 使用版本計算 action。
+      uses: https://gitea.jsc.idv.tw/actions/calculate-version@${{ vars.ACTION_CALCULATE_VERSION }}
+      # 傳入 action 參數。
       with:
+        # 告知 action 是否為 beta 分支情境。
+        is_beta: ${{ env.IS_BETA }}
+    # 發佈 release。
+    - name: Publishing Release
+      # 使用 release action 發佈版本。
+      uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
+      # 這裡在 step 層覆寫 VERSION，實際是否可被後續 expression 正確取得，需人工確認。
+      env:
+        # 取前一步算出的版本號。
+        VERSION: ${{ steps.calculate-version.outputs.version }}
+      with:
+        # release 名稱包含 repository 名稱與版本號。
         name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
+        # tag 名稱與版本號保持一致。
         tag_name: "v${{ env.VERSION }}"
+        # 指定這次 release 對應的 commit。
         target_commitish: ${{ gitea.sha }}
+        # beta 分支才標記為 prerelease。
         prerelease: ${{ env.IS_BETA }}
+  # 第二階段：在 beta 情況下執行工具鏈與清理動作
   test:
+    # Job 名稱，會顯示在 UI 中
     name: 2. TEST
+    # 執行環境為 Ubuntu runner
     runs-on: ubuntu
+    # 依賴 build job 的輸出
     needs: [build]
+    # 只有 build 判定為 beta 時才執行
     if: ${{ needs.build.outputs.is_beta == 'true' }}
+    # 由 build job 傳入版本號
     env:
       VERSION: ${{ needs.build.outputs.version }}
+    # 對外輸出的 job 結果
     outputs:
+      # 目前 workflow 內沒有名為 docker-template 的 step；此輸出是否可取得需人工確認。
       message: ${{ steps.docker-template.outputs.message }}
+    # 具體步驟
     steps:
-    - name: Run Docker Template
-      id: docker-template
-      uses: https://gitea.jsc.idv.tw/actions/docker-template@v${{ env.VERSION }}
+    # 安裝或設定 LLM CLI。
+    - name: Setup LLM CLI
+      # 使用對應的 setup action。
+      uses: https://gitea.jsc.idv.tw/actions/setup-${{ vars.ACTION_SETUP_LLM_CLI }}
+      # 傳入設定。
+      with:
+        # LLM CLI 的 OAuth 憑證。
+        oauth: ${{ secrets.LLM_OAUTH }}
+    # 執行 AI Code Review action。
+    - name: Run AI Code Review
+      # step id，方便追蹤。
+      id: ai-code-review
+      # 使用本 repo 發佈的 action。
+      uses: https://gitea.jsc.idv.tw/actions/ai-code-review@${{ vars.ACTION_AI_CODE_REVIEW_VERSION }}
+      # action 參數。
+      with:
+        # 存取 Gitea API 的 token。
+        token: ${{ secrets.TOKEN }}
+        # 指定 LLM 模型名稱。
+        model: ${{ vars.LLM_NAME }}
+    # 執行 cleanup-release action。
+    - name: Run Cleanup Release
+      # 這裡使用 build job 的版本輸出組出 tag；若版本來源不同，需人工確認。
+      uses: https://gitea.jsc.idv.tw/actions/cleanup-release@v${{ env.VERSION }}
+  # 第三階段：輸出結果
   result:
+    # Job 名稱，會顯示在 UI 中
     name: 3. RESULT
+    # 執行環境為 Ubuntu runner
     runs-on: ubuntu
+    # 依賴 build 與 test job 完成
     needs: [build,test]
+    # 取得 build job 輸出的版本
     env:
-      MESSAGE: ${{ needs.test.outputs.message }}
+      VERSION: ${{ needs.build.outputs.version }}
+    # 具體步驟
     steps:
-    - name: Show Message
-      run: echo "$MESSAGE"
+    # 顯示版本，讓執行紀錄可直接查看。
+    - name: Show Version
+      run: echo "$VERSION"

.gitea/workflows/master.yaml

@@ -1,21 +1,39 @@
+# 檔案用途：在 master 分支推送後進行部署相關檢查與標籤顯示
+# 更新日期：2026/07/11 21:02:25
+
+# Workflow 名稱，代表這條 CD 流程
 name: CD
+
+# 觸發條件設定
 on:
+  # 只有 push 到 master 分支時才執行
   push:
     branches:
     - master
+
+# 工作流程中的 jobs
 jobs:
+  # 部署階段，負責取 commit tag 並輸出
   deploy:
+    # Job 名稱，會顯示在 UI 中
     name: DEPLOY
+    # 執行環境為 Ubuntu runner
     runs-on: ubuntu
+    # 設定環境變數，取出第二個 commit 的 id
     env:
       COMMIT_SHA: ${{ gitea.event.commits[1].id }}
+    # 具體步驟
     steps:
+    # checkout source code，供後續 git describe 使用
     - name: Source Code Checkout
       uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
       with:
+        # 保留完整歷史，讓 git describe 可運作
         fetch-depth: 0
+    # 取出包含目前 commit 的 tag
     - name: Get Commit Tag
       id: commit
       run: echo "tag=$(git describe --contains ${{ env.COMMIT_SHA }})" >> $GITEA_OUTPUT
+    # 顯示 tag，讓執行紀錄可直接查看
     - name: Show Tag
       run: echo "${{ steps.commit.outputs.tag }}"

.gitea/workflows/readme.md

@@ -1,9 +1,52 @@
-# GITEA COMPOSITE ACTION 的工作流列表
+# GITEA 工作流說明
 
-- CI
-  - BUILD
-  - TEST
-  - RESULT
-- CD
-  - BUILD
-  - DEPLOY
+## 總覽
+
+目前專案內有 2 條 workflow 與 1 份 workflow README 文件：
+
+| Workflow 名稱 | 檔案位置 | 觸發條件 | 用途 |
+| --- | --- | --- | --- |
+| CI | `.gitea/workflows/ci.yaml` | `pull_request` 到 `master`、`develop`，事件類型為 `opened`、`synchronize` | 在 PR 階段建立版本、發佈 release，並在 beta 情境下執行工具鏈與清理動作 |
+| CD | `.gitea/workflows/master.yaml` | `push` 到 `master` | 在主分支推送後取得 commit tag，作為部署或版本追蹤依據 |
+| WORKFLOW README | `.gitea/workflows/readme.md` | 文件檔，無觸發條件 | 整理 workflow 名稱、觸發條件與注意事項，方便維護與查閱 |
+
+## CI
+
+- 檔案位置：`.gitea/workflows/ci.yaml`
+- 用途：在 pull request 階段先建立版本、發佈 release，並在 beta 情境下執行後續工具鏈與清理動作。
+- 觸發條件：PR 指向 `master` 或 `develop`，且事件為 `opened` 或 `synchronize`。
+- 主要參數：
+  - `vars.ACTION_CALCULATE_VERSION`：版本計算 action 版本。
+  - `vars.ACTION_GITEA_RELEASE_VERSION`：release action 版本。
+  - `vars.ACTION_SETUP_LLM_CLI`：LLM CLI 設定 action 名稱或版本識別。
+  - `vars.ACTION_AI_CODE_REVIEW_VERSION`：AI code review action 版本。
+  - `vars.LLM_NAME`：模型名稱。
+  - `secrets.LLM_OAUTH`：LLM CLI OAuth 憑證。
+  - `secrets.TOKEN`：Gitea API token。
+  - `gitea.run_number`、`gitea.base_ref`、`gitea.sha`：版本號、beta 判斷與 release target commit。
+- 重要注意事項：
+  - `build` job 先計算版本，再發佈 release；`Publishing Release` 這個 step 的 `env.VERSION` 是否能被後續表達式正確使用，需人工確認。
+  - `test` job 目前有 `outputs.message` 指向 `steps.docker-template.outputs.message`，但現有 steps 中沒有 `docker-template` step，這一點需人工確認。
+  - `Run Cleanup Release` 目前使用 `env.VERSION` 組 action 版本字串，實際是否與預期發布版本一致，需人工確認。
+  - `result` job 只輸出版本號，不再輸出訊息內容，與舊版流程不同。
+
+## CD
+
+- 檔案位置：`.gitea/workflows/master.yaml`
+- 用途：在 `master` 分支推送後 checkout 原始碼並顯示對應 commit tag。
+- 觸發條件：`push` 到 `master`。
+- 主要參數：
+  - `vars.ACTION_CHECKOUT_VERSION`：checkout action 版本。
+  - `gitea.event.commits[1].id`：用於 `git describe --contains` 的 commit SHA。
+  - `GITEA_OUTPUT`：job step 輸出檔案。
+- 重要注意事項：
+  - `gitea.event.commits[1]` 的索引是否一定存在，需人工確認，避免 push 內容少於兩筆 commit 時出錯。
+  - `fetch-depth: 0` 是為了讓 `git describe` 能讀取完整歷史，不能省略。
+
+## readme
+
+- 檔案位置：`.gitea/workflows/readme.md`
+- 用途：整理 workflow 名稱、觸發條件與注意事項，方便快速查閱。
+- 觸發條件：無，這是文件檔。
+- 主要參數：無。
+- 重要注意事項：此文件不改動任何 workflow 設定，只負責說明與彙整。

Dockerfile

@@ -1,11 +1,23 @@
-ARG NODE_VERSION=alpine
+# 檔案用途：建立執行 cleanup-release action 的 Node.js 容器映像
+# 更新日期：2026/07/11 21:02:25
 
+# 允許在建置時指定 Node.js 版本標籤
+ARG NODE_VERSION=22-alpine
+
+# 使用指定版本的 Node.js 基底映像
 FROM node:${NODE_VERSION}
+
+# 設定 action 容器內的工作目錄
 WORKDIR /action
 
+# 複製程式碼到容器內，讓 entrypoint 可以執行主程式
 COPY src/ /action/src/
+
+# 複製入口腳本到容器內
 COPY entrypoint.sh /action/entrypoint.sh
 
+# 確保入口腳本可執行
 RUN chmod +x /action/entrypoint.sh
 
+# 容器啟動時固定執行入口腳本
 ENTRYPOINT ["/action/entrypoint.sh"]

README.md

@@ -0,0 +1,33 @@
+# cleanup-release
+
+更新時間：2026/07/11 21:02:25
+
+這是一個 Gitea Docker action，用來清理舊版 release 與未對應 release 的 tag。
+
+## 專案列表
+
+### 專案描述表
+
+| 專案名稱 | 專案描述 |
+| --- | --- |
+| [cleanup-release](https://gitea.jsc.idv.tw/actions/cleanup-release/src/branch/develop/) | 此專案提供一個清理舊版成品的 Gitea Docker action。 |
+
+### 參考專案表
+
+| 專案名稱 | 參考專案列表 |
+| --- | --- |
+| [cleanup-release](https://gitea.jsc.idv.tw/actions/cleanup-release/src/branch/develop/) | 無 |
+
+### NuGet 套件表
+
+| 專案名稱 | NuGet 套件列表 |
+| --- | --- |
+| [cleanup-release](https://gitea.jsc.idv.tw/actions/cleanup-release/src/branch/develop/) | 無 |
+
+## 功能列表
+
+此專案沒有可列入 README 的公開方法，因此不產生功能表。
+
+## 使用範例
+
+此專案沒有公開方法可提供範例。

action.yml

@@ -1,14 +1,41 @@
-name: 'Gitea Docker Template'
-description: 'Gitea Docker 範本'
+# 檔案用途：定義 CLEANUP OLD RELEASES 這個 Docker action 的輸入參數與執行環境
+# 更新日期：2026/07/11 21:02:25
+
+# Action 名稱，會顯示在 action 市集與文件中
+name: 'CLEANUP OLD RELEASES'
+
+# Action 描述，簡短說明這個 action 的目的
+description: '清理舊版成品'
+
+# 作者資訊，標示此 action 的維護者
 author: 'Jeffery'
+
+# 定義可由使用者或呼叫端傳入的輸入參數
 inputs:
-  message:
-    description: '輸入訊息'
-    required: false
-    default: 'Hello, World!'
-outputs:
-  message:
-    description: '輸出訊息'
+  # RUNNER_TOKEN 用於授權呼叫 Gitea API；未提供時會改用 secrets
+  RUNNER_TOKEN:
+    # 參數說明，讓呼叫端知道這是 Runner Token
+    description: 'Gitea Runner Token'
+  # KEEP_COUNT 用於控制保留的 release 數量
+  KEEP_COUNT:
+    # 參數說明，這裡表示保留的版本數量
+    description: '保留的版本數量'
+    # 預設保留 2 個版本，避免完全刪除歷史 release
+    default: '2'
+
+# 定義 action 的執行方式
 runs:
+  # 使用 Docker image 作為執行環境
   using: docker
+  # Dockerfile 位於 repo 根目錄
   image: Dockerfile
+  # 將 Gitea 與輸入參數映射為容器環境變數
+  env:
+    # GITEA_SERVER_URL 由 Gitea runtime 注入，供程式組 API URL
+    GITEA_SERVER_URL: ${{ gitea.server_url }}
+    # GITEA_REPOSITORY 由 Gitea runtime 注入，供程式指定目標 repo
+    GITEA_REPOSITORY: ${{ gitea.repository }}
+    # 優先使用傳入的 RUNNER_TOKEN，否則退回 Gitea token secrets
+    RUNNER_TOKEN: ${{ inputs.RUNNER_TOKEN || secrets.GITEA_TOKEN || secrets.RUNNER_TOKEN }}
+    # KEEP_COUNT 直接沿用輸入值，交由程式驗證
+    KEEP_COUNT: ${{ inputs.KEEP_COUNT }}

entrypoint.sh

@@ -1,10 +1,12 @@
 #!/bin/sh
+# 檔案用途：啟動 action 容器時輸出識別資訊，並交由 Node 主程式執行
+# 更新日期：2026/07/11 21:02:25
+
 set -e
 
-echo "================================================"
-echo "Action  : Gitea Docker Template"
-echo "用途    : Gitea Docker 範本"
-echo "更新時間: 2026/07/02 09:41:31"
-echo "================================================"
+ts=$(TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S')
+printf '[INF][%s]: Action: CLEANUP OLD RELEASES\n' "$ts"
+printf '[INF][%s]: 用途: 清理舊版成品\n' "$ts"
+printf '[INF][%s]: 更新時間: 2026/07/11\n' "$ts"
 
 exec node /action/src/index.js "$@"

src/index.js

@@ -1,15 +1,540 @@
-const fs = require('fs');
+const https = require('https');
 
-function main() {
-  const message = process.env.INPUT_MESSAGE || '';
-  const outputPath = process.env.GITHUB_OUTPUT;
-  const line = `message=${message}\n`;
+const DELETE_CONCURRENCY = 4;
+const MAX_PAGES = 1000;
 
-  if (outputPath) {
-    fs.appendFileSync(outputPath, line);
+const keepAliveAgent = new https.Agent({ keepAlive: true });
+
+const taipeiFormatter = new Intl.DateTimeFormat('en-CA', {
+  timeZone: 'Asia/Taipei',
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hourCycle: 'h23',
+});
+
+let currentStage = '';
+let cachedTimestampKey = '';
+let cachedTimestampValue = '';
+
+/**
+ * 格式化台灣時區時間，供 log 使用。
+ *
+ * @param {Date} [date=new Date()] 要格式化的時間。
+ * @returns {string} `yyyy/MM/dd HH:mm:ss` 格式時間字串。
+ */
+function formatTaipeiTimestamp(date = new Date()) {
+  const timestampKey = date.toISOString().slice(0, 19);
+  if (timestampKey === cachedTimestampKey) {
+    return cachedTimestampValue;
+  }
+
+  const parts = taipeiFormatter.formatToParts(date);
+
+  const lookup = {};
+  for (const part of parts) {
+    if (part.type !== 'literal') {
+      lookup[part.type] = part.value;
+    }
+  }
+
+  cachedTimestampKey = timestampKey;
+  cachedTimestampValue = `${lookup.year}/${lookup.month}/${lookup.day} ${lookup.hour}:${lookup.minute}:${lookup.second}`;
+  return cachedTimestampValue;
+}
+
+/**
+ * 將未信任內容整理成適合記錄到 log 或錯誤訊息的文字。
+ *
+ * @param {*} value 原始值。
+ * @returns {string} 已去除控制字元的文字。
+ */
+function sanitizeLogText(value) {
+  return String(value).replace(/[\u0000-\u001f\u007f]/g, ' ');
+}
+
+/**
+ * 將回應內容整理成適合放進例外訊息的摘要。
+ *
+ * @param {*} body 回應內容。
+ * @param {number} [maxLength=200] 最長保留長度。
+ * @returns {string} 已整理的回應摘要。
+ */
+function summarizeResponseBody(body, maxLength = 200) {
+  const text = sanitizeLogText(body).replace(/\s+/g, ' ').trim();
+  if (text.length <= maxLength) {
+    return text;
+  }
+
+  return `${text.slice(0, maxLength)}…`;
+}
+
+/**
+ * 組合統一格式的 log 字串。
+ *
+ * @param {string} level 訊息等級。
+ * @param {string} message 訊息內容。
+ * @returns {string} 已格式化的 log 字串。
+ */
+function formatLog(level, message) {
+  const stagePrefix = currentStage ? `[${sanitizeLogText(currentStage)}]` : '';
+  return `${stagePrefix}[${level}][${formatTaipeiTimestamp()}]: ${sanitizeLogText(message)}`;
+}
+
+/**
+ * 輸出標準輸出訊息。
+ *
+ * @param {string} level 訊息等級。
+ * @param {string} message 訊息內容。
+ */
+function writeStdout(level, message) {
+  process.stdout.write(`${formatLog(level, message)}\n`);
+}
+
+/**
+ * 輸出標準錯誤訊息。
+ *
+ * @param {string} level 訊息等級。
+ * @param {string} message 訊息內容。
+ */
+function writeStderr(level, message) {
+  process.stderr.write(`${formatLog(level, message)}\n`);
+}
+
+/**
+ * 切換目前訊息所屬區塊，供 log 前綴使用。
+ *
+ * @param {string} title 區塊名稱。
+ */
+function section(title) {
+  currentStage = title;
+}
+
+/**
+ * 輸出一般資訊訊息。
+ *
+ * @param {string} message 訊息內容。
+ */
+function info(message) {
+  writeStdout('INF', message);
+}
+
+/**
+ * 輸出警告訊息。
+ *
+ * @param {string} message 訊息內容。
+ */
+function warn(message) {
+  writeStdout('WRN', message);
+}
+
+/**
+ * 輸出錯誤訊息。
+ *
+ * @param {string} message 訊息內容。
+ */
+function fail(message) {
+  writeStderr('ERR', message);
+}
+
+/**
+ * 判斷值是否視為空值。
+ *
+ * @param {*} value 要檢查的值。
+ * @returns {boolean} 如果是空值則回傳 `true`。
+ */
+function isEmptyOrNull(value) {
+  return value === undefined || value === null || value === '';
+}
+
+/**
+ * 正規化環境變數值；workflow 模板缺值時可能代入字面值 `'null'`，一律視為未提供。
+ *
+ * @param {string | undefined} value 環境變數原始值。
+ * @returns {string | undefined} 正規化後的值。
+ */
+function normalizeEnvValue(value) {
+  return value === 'null' ? undefined : value;
+}
+
+/**
+ * 將 URL 遮罩成只含 origin 的文字，供 log 使用。
+ *
+ * @param {*} value 原始 URL 值。
+ * @returns {string} 遮罩後的 origin，無法解析時回傳提示文字。
+ */
+function maskUrlForLog(value) {
+  try {
+    return new URL(String(value)).origin;
+  } catch (error) {
+    return '[invalid URL]';
+  }
+}
+
+/**
+ * 驗證必要值是否存在。
+ *
+ * @param {string} name 參數名稱。
+ * @param {*} value 參數值。
+ * @param {*} [displayValue=value] 寫進 log 的顯示值，敏感內容可先遮罩。
+ */
+function requireValue(name, value, displayValue = value) {
+  info(`${name}=${displayValue}`);
+
+  if (isEmptyOrNull(value)) {
+    fail(`${name} is required`);
+    process.exit(1);
+  }
+}
+
+/**
+ * 驗證字串是否為正整數，且落在安全整數範圍內；下限 1 可避免把保留數設成 0 而清空所有 release。
+ *
+ * @param {string} name 參數名稱。
+ * @param {string} value 參數值。
+ */
+function requirePositiveInteger(name, value) {
+  if (!/^[0-9]+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1) {
+    fail(`${name} must be a positive integer within the safe integer range`);
+    process.exit(1);
+  }
+}
+
+/**
+ * 驗證值是否為合法的 HTTPS 絕對 URL，避免 URL 解析失敗留到主流程中途才拋出。
+ *
+ * @param {string} name 參數名稱。
+ * @param {*} value 參數值。
+ */
+function requireHttpsUrl(name, value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value));
+  } catch (error) {
+    fail(`${name} must be a valid absolute URL`);
+    process.exit(1);
+  }
+
+  if (parsed.protocol !== 'https:') {
+    fail(`${name} must use HTTPS`);
+    process.exit(1);
+  }
+}
+
+/**
+ * 驗證 repository 是否為 `owner/repo` 格式且僅含安全字元，拒絕 `.`、`..` 等路徑片段。
+ *
+ * @param {string} name 參數名稱。
+ * @param {*} value 參數值。
+ */
+function requireRepository(name, value) {
+  const segments = String(value).split('/');
+  const isValidSegment = (segment) =>
+    /^[A-Za-z0-9_.-]+$/.test(segment) && segment !== '.' && segment !== '..';
+
+  if (segments.length !== 2 || !segments.every(isValidSegment)) {
+    fail(`${name} must be in owner/repo format`);
+    process.exit(1);
+  }
+}
+
+/**
+ * 對指定 URL 發送 request，回傳狀態碼與 body。
+ *
+ * @param {string} url 完整目標網址。
+ * @param {{ method?: string, headers?: Record<string, string>, collectBody?: boolean }} [options] request 設定；`collectBody` 為 `false` 時丟棄回應內容、只保留狀態碼。
+ * @returns {Promise<{ statusCode: number, body: string }>} 回應狀態碼與內容。
+ */
+function request(url, { method = 'GET', headers = {}, collectBody = true } = {}) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(url);
+    if (target.protocol !== 'https:') {
+      reject(new Error(`Refusing to send request to non-HTTPS URL: ${target.origin}`));
+      return;
+    }
+
+    const req = https.request(
+      target,
+      {
+        method,
+        headers,
+        agent: keepAliveAgent,
+      },
+      (res) => {
+        const statusCode = res.statusCode || 0;
+
+        if (!collectBody) {
+          res.resume();
+          res.on('end', () => {
+            resolve({ statusCode, body: '' });
+          });
+          return;
+        }
+
+        const chunks = [];
+
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          chunks.push(chunk);
+        });
+        res.on('end', () => {
+          resolve({
+            statusCode,
+            body: chunks.join(''),
+          });
+        });
+      },
+    );
+
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+/**
+ * 逐頁抓取 JSON 陣列資料，直到回傳空頁為止；超過 `MAX_PAGES` 即中止並回報異常。
+ *
+ * @param {string} baseUrl 不含 page 參數的 API URL。
+ * @param {Record<string, string>} headers request 標頭。
+ * @returns {Promise<any[]>} 合併後的陣列資料。
+ */
+async function fetchAllPages(baseUrl, headers) {
+  const all = [];
+
+  for (let page = 1; ; page += 1) {
+    if (page > MAX_PAGES) {
+      throw new Error(`GET ${baseUrl} 分頁超過 ${MAX_PAGES} 頁上限，中止抓取以避免無限迴圈`);
+    }
+
+    const pageUrl = `${baseUrl}?page=${page}`;
+    const { statusCode, body } = await request(pageUrl, { headers });
+
+    if (statusCode < 200 || statusCode >= 300) {
+      throw new Error(`GET ${pageUrl} failed with HTTP ${statusCode}: ${summarizeResponseBody(body)}`);
+    }
+
+    let data;
+    try {
+      data = JSON.parse(body || '[]');
+    } catch (error) {
+      throw new Error(`GET ${pageUrl} returned invalid JSON: ${summarizeResponseBody(body)}`);
+    }
+
+    if (!Array.isArray(data)) {
+      throw new Error(`GET ${pageUrl} did not return a JSON array`);
+    }
+
+    if (data.length === 0) {
+      break;
+    }
+
+    all.push(...data);
+  }
+
+  return all;
+}
+
+/**
+ * 對指定 URL 發送 DELETE request。
+ *
+ * @param {string} url 要刪除的資源網址。
+ * @param {Record<string, string>} headers request 標頭。
+ * @returns {Promise<{ statusCode: number, body: string }>} 回應狀態碼與內容。
+ */
+async function deleteResource(url, headers) {
+  return request(url, {
+    method: 'DELETE',
+    headers,
+    collectBody: false,
+  });
+}
+
+/**
+ * 以固定批次大小處理項目，降低逐筆等待造成的延遲；單筆例外不會中止同批其他項目。
+ *
+ * @param {any[]} items 要處理的項目。
+ * @param {number} batchSize 每批同時處理的數量。
+ * @param {(item: any) => Promise<boolean>} handler 單筆處理函式，回傳該筆是否成功。
+ * @returns {Promise<PromiseSettledResult<boolean>[]>} 依原始順序排列的處理結果。
+ */
+async function processInBatches(items, batchSize, handler) {
+  const results = [];
+
+  for (let index = 0; index < items.length; index += batchSize) {
+    const batch = items.slice(index, index + batchSize);
+    results.push(...(await Promise.allSettled(batch.map((item) => handler(item)))));
+  }
+
+  return results;
+}
+
+/**
+ * 彙總批次結果；記錄被 reject 的例外，並回傳是否有任何一筆失敗。
+ *
+ * @param {PromiseSettledResult<boolean>[]} results 批次處理結果。
+ * @returns {boolean} 只要有任一筆失敗即回傳 `true`。
+ */
+function hasBatchFailure(results) {
+  let failed = false;
+
+  for (const result of results) {
+    if (result.status === 'rejected') {
+      failed = true;
+      const reason = result.reason;
+      fail(`批次處理發生例外: ${reason instanceof Error ? reason.message : String(reason)}`);
+    } else if (result.value === false) {
+      failed = true;
+    }
+  }
+
+  return failed;
+}
+
+/**
+ * 執行 release 與 tag 清理流程。
+ */
+async function main() {
+  const GITEA_SERVER_URL = normalizeEnvValue(process.env.GITEA_SERVER_URL);
+  const GITEA_REPOSITORY = normalizeEnvValue(process.env.GITEA_REPOSITORY);
+  const RUNNER_TOKEN = normalizeEnvValue(process.env.RUNNER_TOKEN) ?? '';
+  const KEEP_COUNT = normalizeEnvValue(process.env.KEEP_COUNT) ?? '';
+
+  section('參數檢查');
+  requireValue('GITEA_SERVER_URL', GITEA_SERVER_URL, maskUrlForLog(GITEA_SERVER_URL));
+  requireHttpsUrl('GITEA_SERVER_URL', GITEA_SERVER_URL);
+  requireValue('GITEA_REPOSITORY', GITEA_REPOSITORY);
+  requireRepository('GITEA_REPOSITORY', GITEA_REPOSITORY);
+  requireValue('KEEP_COUNT', KEEP_COUNT);
+  requirePositiveInteger('KEEP_COUNT', KEEP_COUNT);
+
+  const keepCount = Number(KEEP_COUNT);
+  const authHeaders = {};
+  if (isEmptyOrNull(RUNNER_TOKEN)) {
+    warn('RUNNER_TOKEN is empty; release API calls will be anonymous');
   } else {
-    process.stdout.write(line);
+    info('RUNNER_TOKEN=[redacted]');
+    authHeaders.Authorization = `token ${RUNNER_TOKEN}`;
+  }
+
+  const serverBase = new URL(GITEA_SERVER_URL);
+  serverBase.username = '';
+  serverBase.password = '';
+  serverBase.search = '';
+  serverBase.hash = '';
+  const serverBaseUrl = serverBase.toString().replace(/\/+$/, '');
+
+  const repositoryPath = GITEA_REPOSITORY.split('/').map(encodeURIComponent).join('/');
+  const releaseApiUrl = `${serverBaseUrl}/api/v1/repos/${repositoryPath}/releases`;
+
+  section('取得成品資訊');
+  info(`GET ${releaseApiUrl}`);
+
+  const releaseJson = await fetchAllPages(releaseApiUrl, authHeaders);
+  releaseJson.sort((left, right) => {
+    if (left.created_at < right.created_at) {
+      return 1;
+    }
+
+    if (left.created_at > right.created_at) {
+      return -1;
+    }
+
+    return 0;
+  });
+
+  const releaseCount = releaseJson.length;
+  info(`RELEASE_COUNT=${releaseCount}`);
+  info(`KEEP_COUNT=${KEEP_COUNT}`);
+
+  if (releaseCount <= keepCount) {
+    info('沒有需要清理的舊版本成品');
+  } else {
+    section('刪除舊版本成品');
+
+    const releaseToDelete = releaseJson.slice(keepCount);
+    const releaseResults = await processInBatches(releaseToDelete, DELETE_CONCURRENCY, async (releaseItem) => {
+      const releaseId = releaseItem?.id;
+      if (!Number.isSafeInteger(releaseId) || releaseId <= 0) {
+        warn(
+          `略過 id 不是正整數的成品: ${sanitizeLogText(releaseItem?.tag_name || '')} (${sanitizeLogText(releaseItem?.name || '')})`,
+        );
+        return true;
+      }
+
+      const releaseTag = sanitizeLogText(releaseItem.tag_name || '');
+      const releaseName = sanitizeLogText(releaseItem.name || '');
+      const deleteUrl = `${releaseApiUrl}/${releaseId}`;
+      info(`DELETE ${releaseTag} (${releaseName})`);
+
+      const { statusCode } = await deleteResource(deleteUrl, authHeaders);
+      if (statusCode === 204) {
+        info(`成功刪除: ${releaseTag} (${releaseName})`);
+        return true;
+      }
+
+      fail(`刪除失敗: ${releaseTag} (${releaseName}), HTTP ${statusCode}`);
+      return false;
+    });
+
+    if (hasBatchFailure(releaseResults)) {
+      throw new Error('至少有一筆 release 刪除失敗');
     }
   }
 
-main();
+  section('刪除未指定 release 的 tag');
+
+  const releaseTags = new Set(
+    releaseJson
+      .slice(0, keepCount)
+      .map((item) => item?.tag_name)
+      .filter((tag) => !isEmptyOrNull(tag)),
+  );
+
+  const tagApiUrl = `${serverBaseUrl}/api/v1/repos/${repositoryPath}/tags`;
+  info(`GET ${tagApiUrl}`);
+
+  const tagJson = await fetchAllPages(tagApiUrl, authHeaders);
+  info(`TAG_COUNT=${tagJson.length}`);
+
+  const tagResults = await processInBatches(tagJson, DELETE_CONCURRENCY, async (tagItem) => {
+    const tagName = tagItem?.name;
+    if (isEmptyOrNull(tagName)) {
+      warn('略過沒有名稱的 tag');
+      return true;
+    }
+
+    const safeTagName = sanitizeLogText(tagName);
+    if (releaseTags.has(tagName)) {
+      info(`保留指定 release 的 tag: ${safeTagName}`);
+      return true;
+    }
+
+    const deleteUrl = `${tagApiUrl}/${encodeURIComponent(tagName)}`;
+    info(`DELETE tag ${safeTagName}`);
+
+    const { statusCode } = await deleteResource(deleteUrl, authHeaders);
+    if (statusCode === 204) {
+      info(`成功刪除未指定 release 的 tag: ${safeTagName}`);
+      return true;
+    }
+
+    fail(`刪除 tag 失敗: ${safeTagName}, HTTP ${statusCode}`);
+    return false;
+  });
+
+  if (hasBatchFailure(tagResults)) {
+    throw new Error('至少有一筆 tag 刪除失敗');
+  }
+}
+
+main()
+  .catch((error) => {
+    fail(error instanceof Error ? error.stack || error.message : String(error));
+    process.exitCode = 1;
+  })
+  .finally(() => {
+    keepAliveAgent.destroy();
+  });