# Release Tag Version

更新時間：2026/06/26 10:47:20

本專案為 Gitea Actions 的 **composite action**，用來自動計算版本號、建立 release 並標註對應 tag，最後清理舊成品。

## 專案列表

### 專案描述

| 專案名稱 | 專案描述 |
| --- | --- |
| [Release Tag Version](https://gitea.jsc.idv.tw/composite-actions/release-tag-version/src/branch/develop) | Gitea composite action，依序呼叫 calculate-version 計算版本號、組合 release 參數、以 akkuman/gitea-release-action 建立 release 與 tag，再以 release-cleanup 清理舊成品。此專案未公開可列入 README 的程式方法。 |

### 參考專案

| 專案名稱 | 參考專案列表 |
| --- | --- |
| [Release Tag Version](https://gitea.jsc.idv.tw/composite-actions/release-tag-version/src/branch/develop) | 無 |

### NuGet 套件

| 專案名稱 | NuGet 套件列表 |
| --- | --- |
| [Release Tag Version](https://gitea.jsc.idv.tw/composite-actions/release-tag-version/src/branch/develop) | 無 |

## 功能列表

本專案為 YAML 定義的 Gitea composite action 與 workflow，未包含任何可文件化的 public method、public constructor、public extension method 或 public operator，因此沒有可列入的功能項目。

## 使用範例

本專案不提供程式方法，而是提供一個可被其他 workflow 引用的 Gitea composite action。

### 在其他 repo 的 workflow 中引用

```yaml
steps:
- name: 取得程式碼
  uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
- name: 釋出並標註成品版本
  uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@<version>
  with:
    # files 為非必填；指定要隨 release 一起釋出（上傳）的成品檔案，可省略。
    files: dist/*
```

### 本 repo 內的 CD workflow（`.gitea/workflows/cd.yaml`）

```yaml
on:
  push:
    branches:
    - master
jobs:
  release-tag-version:
    name: Release Tag Version
    runs-on: ubuntu
    steps:
    - name: 取得程式碼
      uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
    - name: 釋出並標註成品版本
      # uses: ./ 引用本 repo 根目錄的 composite action（action.yml）
      uses: ./
```

### 執行流程與前置條件

引用後，composite action 會依序執行：

1. **版本號計算**：呼叫 `docker-actions/calculate-version` 算出本次版本號。
2. **組合釋出參數**：版本號非空時，組出 release 的 `name`（格式 `<repo 名稱> v<版本>`）與 `tag_name`（格式 `v<版本>`）。
3. **檢查版本號輸出**：版本號為空時輸出錯誤訊息並 `exit 1`，中止流程，避免建立錯誤的 release/tag。
4. **釋出並標註成品版本**：以 `akkuman/gitea-release-action` 建立 release 並打 tag，附帶 `files` 指定的成品。
5. **清理舊成品**：呼叫 `docker-actions/release-cleanup` 清理過舊的 release。

**前置條件**（需於 Gitea repo/organization 環境設定）：

- 變數 `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，並清理舊成品。