# ===================================================================
# 用途：Gitea CI workflow，於 Pull Request 開啟（opened）或同步更新（synchronize）時觸發（master 分支除外）。
#       流程先呼叫 composite action `release-tag-version`（is_beta: true）標註一個 beta 成品版本並輸出版本號，
#       再以該 beta 版本（@v${version}）執行本專案的 `release-cleanup` action，對自身成品做清理（dogfooding 自我清理驗證）。
# 更新日期（台灣時區 Asia/Taipei）：2026/07/01 09:14:10
# ===================================================================

# workflow 名稱，顯示於 Gitea Actions 介面
name: CI
# 觸發事件設定
on:
  # 針對 Pull Request 事件觸發
  pull_request:
    # 目標分支過濾：忽略以下分支（即 master 不觸發本 workflow）
    branches-ignore:
    # 排除 master 分支，避免對正式主線的 PR 執行本流程
    - master
    # 僅在 PR 被「開啟（opened）」或「推送新 commit 同步（synchronize）」時觸發
    types: [opened, synchronize]
# 定義所有 jobs
jobs:
  # 第一個 job: 釋出並標註成品版本,並將版本號往外拋給後續 job 使用。
  release-tag-version:
    # job 顯示名稱。
    name: Release Tag Version
    # 指定執行環境 (runner) 標籤為 ubuntu。
    runs-on: ubuntu
    # 宣告此 job 的輸出,供後續 needs 此 job 的其他 job 取用。
    outputs:
      # 將下方 id 為 release-tag-version 的 step 所輸出的 version,設為此 job 的對外 version 輸出 (關鍵點: 透過 outputs 把標註出的版本往外拋)。
      version: ${{ steps.release-tag-version.outputs.version }}
    # 此 job 依序執行的步驟。
    steps:
    # 步驟: 呼叫 composite action 進行釋出並標註成品版本。
    - name: 釋出並標註成品版本
      # 設定此 step 的 id,讓上方 outputs 可用 steps.release-tag-version.outputs.version 取得其輸出。
      id: release-tag-version
      # 引用 release-tag-version composite action,版本以變數 vars.ACTION_RELEASE_TAG_VERSION 釘選 (集中於 repo/org 變數管理,便於統一升版)。
      uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}
      # 傳遞給該 action 的輸入參數。
      with:
        # is_beta 設為 true 表示走 beta 標版流程 (標註的是 beta 成品版本,而非正式版)。
        is_beta: true
  # 第二個 job: 以前一個 job 標註出的 beta 版本執行清理成品 action (dogfooding 自我清理)。
  release-cleanup:
    # job 顯示名稱。
    name: Release Cleanup
    # 指定執行環境 (runner) 標籤為 ubuntu。
    runs-on: ubuntu
    # 宣告相依於 release-tag-version job,確保其先完成且可取用其 outputs.version。
    needs: release-tag-version
    # 此 job 依序執行的步驟。
    steps:
    # 步驟: 呼叫 release-cleanup action 清理舊成品。
    - name: 清理舊成品
      # 引用本專案 release-cleanup action,版本釘選為前一個 job 輸出的 beta 版本 v${version} (以剛標出的 beta 版自我驗證清理流程)。
      uses: https://gitea.jsc.idv.tw/docker-actions/release-cleanup@v${{ needs.release-tag-version.outputs.version }}