release-cleanup/README.md

Release Cleanup

更新時間：2026/06/30 12:02:55（台灣時區 Asia/Taipei）

清理舊成品的 Gitea / GitHub docker container action。依保留數量清理 repo 的舊 release，並刪除沒有對應 release 的 tag；正式版與 beta 版各自獨立保留指定數量。

• 主程式語言：JavaScript（Node.js，使用原生 fetch，需 Node 18+）
• 執行方式：docker container action（action.yaml → Dockerfile → entrypoint.sh → node /app/index.js）

行為總覽

1. 參數檢查：驗證 GITEA_SERVER_URL、GITEA_REPOSITORY、KEEP_COUNT（缺值或 KEEP_COUNT 非整數時以 exit code 1 結束）。
2. 取得成品資訊：取得所有 release，依建立時間由新到舊排序，並以 tag 名稱含 -beta. 與否分為正式版與 beta 版。
3. 刪除舊版本成品：正式版與 beta 版各自保留最新 KEEP_COUNT 筆，刪除其餘 release（單筆刪除失敗只記錄錯誤，不中斷）。
4. 刪除未指定 release 的 tag：重新取得 release 後，刪除所有未被任何 release 指定的 tag。

GITEA_TOKEN 為空時以匿名身分呼叫 API。取得分頁失敗或參數不合法則直接以 exit code 1 結束程序。

Action 輸入與環境變數

名稱	來源	必填	預設	說明
keep_count	inputs	否	2	正式版與 beta 版各自要保留的成品數量
GITEA_SERVER_URL	env（gitea.server_url）	是	—	Gitea 站台 URL
GITEA_REPOSITORY	env（gitea.repository）	是	—	owner/repo 形式的儲存庫
GITEA_TOKEN	env（gitea.token）	否	—	API token；為空時以匿名呼叫

Workflow 使用範例

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Release Cleanup
        uses: docker-actions/release-cleanup@develop
        with:
          keep_count: 3

專案列表

專案描述

專案名稱	專案描述
release-cleanup	清理 Gitea repo 舊 release 與孤兒 tag 的 docker container action；正式版與 beta 版各自保留指定數量

參考專案

專案名稱	參考專案列表
release-cleanup	無

NuGet 套件

專案名稱	NuGet 套件列表
release-cleanup	無

註：本專案為 Node.js 專案，無 .NET ProjectReference 與 NuGet 套件；app/package.json 亦無第三方相依（僅使用 Node 內建 API）。

功能列表

release-cleanup

功能名稱	功能描述
separator	在 stdout 輸出視覺分隔線
section	輸出區段標題區塊
info	以 [INFO] 前綴輸出資訊訊息
success	以 [OK] 前綴輸出成功訊息
warn	以 [WARN] 前綴輸出警告訊息
fail	以 [ERR] 前綴輸出錯誤訊息到 stderr
isEmptyOrNull	判斷值是否視為空 / 未設定
requireValue	檢查必填值，空值時結束程序
requireInteger	驗證非負整數，不符時結束程序
isBeta	判斷名稱是否為 beta 版本
main	Action 主流程：清理舊 release 與孤兒 tag

使用範例

separator

在 stdout 輸出一條前後帶換行、由 50 個等號組成的視覺分隔線，用於在 log 中切割區段。無參數、無回傳值。

separator();
// 輸出：
//
// ==================================================

section

輸出一個區段標題區塊：上緣等號分隔線、標題文字、下緣虛線，用於標示流程進入新階段。

section('參數檢查');
// 輸出：
// ==================================================
// 參數檢查
// --------------------------------------------------

info

以 [INFO] 前綴將一般資訊訊息輸出到 stdout（console.log）。

info('RELEASE_COUNT=10');
// 輸出：[INFO] RELEASE_COUNT=10

success

以 [OK] 前綴將成功訊息輸出到 stdout。

success('成功刪除: v1.0.0 (Release 1.0.0)');
// 輸出：[OK]   成功刪除: v1.0.0 (Release 1.0.0)

warn

以 [WARN] 前綴將警告訊息輸出到 stdout（非致命情況，程式會繼續執行）。

warn('GITEA_TOKEN is empty; release API calls will be anonymous');
// 輸出：[WARN] GITEA_TOKEN is empty; release API calls will be anonymous

fail

以 [ERR] 前綴將錯誤訊息輸出到 stderr（console.error）。僅負責輸出，不會結束程序；是否離開由呼叫端決定。

fail('刪除失敗: v0.1.0 (Release 0.1.0), HTTP 500');
process.exit(1); // 終止由呼叫端負責

isEmptyOrNull

判斷值是否視為「空 / 未設定」，涵蓋 undefined、null、空字串，以及字面字串 'null'（用於處理 CI/環境變數把未設定值帶成字串 "null" 的情況）。

isEmptyOrNull('');      // true
isEmptyOrNull('null');  // true（字面字串）
isEmptyOrNull('abc');   // false

requireValue

檢查必填值。先以 [INFO] 印出 name=value，若值被判定為空則印出 [ERR] 並以 exit code 1 結束程序。

requireValue('GITEA_SERVER_URL', process.env.GITEA_SERVER_URL);
// 值為空 → 輸出 [ERR] GITEA_SERVER_URL is required，並 process.exit(1)

前置條件：應在程式啟動早期呼叫。注意此函式會將值原樣印到 stdout，故不用於機密值（程式對 GITEA_TOKEN 改以 redacted 方式輸出）。

requireInteger

驗證值是否為非負整數字串（正則 /^[0-9]+$/，允許前導零、不允許負號或小數），不符合時印出 [ERR] 並以 exit code 1 結束程序。

requireInteger('KEEP_COUNT', '2');   // 通過
requireInteger('KEEP_COUNT', '-1');  // 輸出 [ERR] ... 並 process.exit(1)

isBeta

判斷 release / tag 名稱是否為 beta 版本，規則為名稱中含有子字串 -beta.。

isBeta('v1.2.3-beta.1'); // true
isBeta('v1.2.3');        // false
isBeta('v1.2.3-beta');   // false（無結尾的點，不符合 -beta.）

main

Action 主流程（async）。讀取環境變數後依序執行參數檢查、取得 release、刪除舊版本（正式版與 beta 版各自保留 KEEP_COUNT 筆）、刪除未指定 release 的 tag。由檔尾 main().catch(...) 立即執行。

// 容器啟動時由 entrypoint.sh 執行：exec node /app/index.js
// 需提供環境變數：
//   GITEA_SERVER_URL、GITEA_REPOSITORY、KEEP_COUNT（必要）、GITEA_TOKEN（選填）
main().catch((err) => {
  fail(err && err.stack ? err.stack : String(err));
  process.exit(1);
});

前置條件：執行環境須提供必要環境變數，且可連線到 Gitea API。結果：清理符合條件的舊 release 與孤兒 tag，並輸出處理過程 log。