first commit

readme.md

@@ -0,0 +1,118 @@
+# Cleanup Old Releases Action
+
+這是一個自動清理舊版本 releases 的 GitHub Action，可以保留指定數量的最新版本，刪除多餘的舊版本。
+
+## 功能特色
+
+- 🗑️ 自動清理舊版本 releases
+- 🔢 可配置保留的版本數量
+- 🔍 支援模擬執行模式
+- 📊 詳細的執行報告
+- 🛡️ 安全的錯誤處理
+
+## 輸入參數
+
+| 參數名稱 | 必要 | 預設值 | 描述 |
+|---------|------|--------|------|
+| `gitea-server` | ✅ | - | Gitea 伺服器 URL |
+| `repository` | ✅ | - | 儲存庫名稱 (格式: owner/repo) |
+| `token` | ✅ | - | Gitea API Token |
+| `keep-count` | ❌ | `2` | 保留的最新版本數量 |
+| `dry-run` | ❌ | `false` | 是否為模擬執行 (只顯示會刪除的版本，不實際刪除) |
+
+## 輸出參數
+
+| 參數名稱 | 描述 |
+|---------|------|
+| `deleted-count` | 已刪除的版本數量 |
+| `deleted-releases` | 已刪除的版本列表 (JSON 格式) |
+
+## 使用範例
+
+### 基本用法 (保留最新2個版本)
+
+```yaml
+- name: 清理舊版本
+  uses: ./.gitea/actions/cleanup-releases
+  with:
+    gitea-server: ${{ gitea.server_url }}
+    repository: ${{ gitea.repository }}
+    token: ${{ secrets.GITEA_TOKEN }}
+```
+
+### 自定義保留數量
+
+```yaml
+- name: 清理舊版本 (保留最新5個)
+  uses: ./.gitea/actions/cleanup-releases
+  with:
+    gitea-server: ${{ gitea.server_url }}
+    repository: ${{ gitea.repository }}
+    token: ${{ secrets.GITEA_TOKEN }}
+    keep-count: '5'
+```
+
+### 模擬執行模式
+
+```yaml
+- name: 檢查要清理的版本
+  id: check-cleanup
+  uses: ./.gitea/actions/cleanup-releases
+  with:
+    gitea-server: ${{ gitea.server_url }}
+    repository: ${{ gitea.repository }}
+    token: ${{ secrets.GITEA_TOKEN }}
+    keep-count: '3'
+    dry-run: 'true'
+
+- name: 顯示模擬結果
+  run: |
+    echo "模擬執行會刪除 ${{ steps.check-cleanup.outputs.deleted-count }} 個版本"
+```
+
+### 使用輸出結果
+
+```yaml
+- name: 清理舊版本
+  id: cleanup
+  uses: ./.gitea/actions/cleanup-releases
+  with:
+    gitea-server: ${{ gitea.server_url }}
+    repository: ${{ gitea.repository }}
+    token: ${{ secrets.GITEA_TOKEN }}
+    keep-count: '2'
+
+- name: 報告清理結果
+  run: |
+    echo "清理完成，刪除了 ${{ steps.cleanup.outputs.deleted-count }} 個舊版本"
+    echo "刪除的版本詳情: ${{ steps.cleanup.outputs.deleted-releases }}"
+```
+
+## 運作邏輯
+
+1. **獲取版本列表**：從 Gitea API 獲取所有 releases，按創建時間排序
+2. **計算刪除範圍**：保留最新的 `keep-count` 個版本，標記其餘版本為待刪除
+3. **執行清理**：
+   - 模擬模式：只顯示會刪除的版本，不實際執行
+   - 正常模式：逐一刪除標記的版本
+4. **回報結果**：提供刪除數量和詳細列表
+
+## 安全特性
+
+- ✅ **防護機制**：如果總版本數 ≤ 保留數量，則不執行任何刪除
+- ✅ **錯誤處理**：API 請求失敗時會顯示錯誤訊息並停止執行
+- ✅ **模擬模式**：可以先模擬執行，確認要刪除的版本無誤
+- ✅ **詳細日誌**：每個步驟都有清楚的日誌輸出
+
+## 注意事項
+
+- 需要有 `GITEA_TOKEN` secret 且具備刪除 releases 的權限
+- 刪除操作是不可逆的，建議先使用模擬模式確認
+- Action 按照創建時間排序，保留最新的版本
+- 建議在 release 創建之後執行此 action
+
+## 錯誤處理
+
+- 如果無法連接到 Gitea API，action 會失敗並顯示錯誤訊息
+- 如果某個版本刪除失敗，會記錄錯誤但繼續處理其他版本
+- 如果 token 權限不足，會顯示相應的 HTTP 錯誤狀態