123 lines
7.6 KiB
YAML
123 lines
7.6 KiB
YAML
# =============================================================================
|
||
# 指令檔用途：
|
||
# 這是一個 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）
|
||
# =============================================================================
|
||
|
||
# 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 會是空值。
|
||
required: 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 的版本，不需改動本檔。
|
||
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 名稱。
|
||
# 最終格式為「<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（格式「<repo 名稱> v<版本>」）。
|
||
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（呼叫方傳入，可為空）。
|
||
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 }}
|