# ============================================================================
# 用途：Gitea Actions CI workflow —— 當 PR 開啟或同步（推新 commit）到 master／develop 時，
#       自動 checkout 完整 git 歷史、計算下一個語意化版本號（develop 走 beta 預發布），
#       接著建立 Gitea Release（副作用：建立 git tag 與 Release），正式版並會清理舊 Release。
# 更新時間：2026/07/17 16:49:21
# ============================================================================

# workflow 名稱：顯示於 Gitea Actions 執行清單，方便辨識這條 CI pipeline
name: CI

# 觸發條件設定區塊
on:
  # 以 pull request 事件觸發（非 push），確保版本計算與發布綁定 PR 流程
  pull_request:
    # 只有目標分支（base branch）為下列分支的 PR 才會觸發
    branches:
    # 正式分支：PR 目標為 master 時發布正式版 Release
    - master
    # 開發分支：PR 目標為 develop 時發布 beta 預發布（prerelease）
    - develop
    # 只在 PR 開啟（opened）與來源分支推新 commit 同步（synchronize）時觸發，
    # 避免 reopened／labeled 等其他 PR 事件重複跑 CI
    types: [opened, synchronize]

# workflow 層級環境變數：所有 job／step 皆可透過 env.* 取用
env:
  # 目前 repo 名稱，取自 Gitea 事件 payload，供後續步驟組合 Release 名稱等用途
  REPOSITORY_NAME: ${{ gitea.event.repository.name }}
  # 是否為 beta（預發布）流程：PR 目標分支為 develop 時為 'true'，否則為 'false'；
  # 注意此值為字串型別，後續 if 條件需以字串比較（== 'false'）
  IS_BETA: ${{ gitea.base_ref == 'develop' }}

# job 定義區塊
jobs:
  # 唯一的 job：建置與發布
  build:
    # job 顯示名稱：於 Gitea Actions 介面顯示為 BUILD
    name: BUILD
    # 指定 runner 標籤：由標籤為 ubuntu 的 Gitea Actions runner 執行
    runs-on: ubuntu
    # 依序執行的步驟
    steps:
    # 步驟 1：checkout 原始碼與完整 git 歷史（含所有 tag），
    # 版本計算需要既有 tag 才能推算下一個版本號
    - name: 取得存取庫資訊 (含 Tag)
      # 使用官方 checkout action；vars.ACTION_CHECKOUT_VERSION 為
      # Gitea 組織/repo 層級變數（Actions variables）提供的 action 版本，集中管理升版
      uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
      with:
        # fetch-depth: 0 代表抓取完整歷史（非 shallow clone），確保 tag 與 commit 歷史齊全
        fetch-depth: 0
    # 步驟 2：依既有 tag 計算下一個語意化版本號
    - name: 計算下一個版本號
      # 使用自建的 calculate-next-version action（gitea.jsc.idv.tw 私有 Gitea 上的 docker action）；
      # vars.ACTION_CALCULATE_NEXT_VERSION 同為 Gitea 組織/repo 變數提供的版本
      uses: https://gitea.jsc.idv.tw/docker-actions/calculate-next-version@${{ vars.ACTION_CALCULATE_NEXT_VERSION }}
      # step id：後續步驟以 steps.calculate-next-version.outputs.value 取得計算結果
      id: calculate-next-version
      with:
        # 傳入是否為 beta：true 時產生預發布版號（例如帶 -beta 後綴），false 時產生正式版號
        is_beta: ${{ env.IS_BETA }}
    # 步驟 3：建立 Gitea Release（副作用：建立對應 git tag 與 Release 頁面）
    # 需人工確認：此步驟在 PR opened/synchronize 就會發布 Release 並打 tag，
    # 亦即 PR 尚未合併前每次推 commit 都會產生 Release；請確認這是預期行為
    # （通常發布會放在 push 到 master/develop 或 PR merged 之後）。
    - name: 發布成品
      # 使用第三方 akkuman/gitea-release-action 建立 Release；
      # vars.ACTION_GITEA_RELEASE_VERSION 為 Gitea 組織/repo 變數提供的 action 版本
      # 需人工確認：此 action 通常需要 GITEA_TOKEN／token 才能建立 Release，
      # 本設定未見明確傳入 token，請確認 runner 預設 token 權限是否足夠。
      uses: akkuman/gitea-release-action@${{ vars.ACTION_GITEA_RELEASE_VERSION }}
      # step 層級環境變數
      env:
        # 將上一步計算出的版本號存為 VERSION，供本步驟的 with 參數引用
        VERSION: ${{ steps.calculate-next-version.outputs.value }}
      with:
        # Release 顯示名稱：{repo 名稱} v{版本號}
        name: "${{ gitea.event.repository.name }} v${{ env.VERSION }}"
        # 要建立的 git tag 名稱：v{版本號}
        tag_name: "v${{ env.VERSION }}"
        # tag 指向的 commit：gitea.sha 為觸發此 workflow 的 commit
        # 需人工確認：pull_request 事件的 sha 通常是 PR 的 merge commit（暫時性 ref），
        # 對其打 tag 可能指向未實際合入分支的 commit，請確認 tag 目標是否符合預期。
        target_commitish: "${{ gitea.sha }}"
        # 是否標記為預發布：develop 目標的 PR 為 true（beta），master 為 false（正式版）
        prerelease: ${{ env.IS_BETA }}
    # 步驟 4：清理舊 Release，避免 Release 清單無限增長
    - name: 清理舊成品
      # 使用自建的 clean-old-release action；
      # vars.ACTION_CLEAN_OLD_RELEASE 為 Gitea 組織/repo 變數提供的 action 版本
      # 需人工確認：其他兩個自建 action 的變數名皆以 _VERSION 結尾，
      # 此變數名為 ACTION_CLEAN_OLD_RELEASE（無 _VERSION 後綴），請確認命名是否刻意如此。
      uses: https://gitea.jsc.idv.tw/docker-actions/clean-old-release@${{ vars.ACTION_CLEAN_OLD_RELEASE }}
      # 僅在非 beta（正式版，PR 目標為 master）時執行清理；
      # 因 env.IS_BETA 為字串，故以 == 'false' 比較
      if: ${{ env.IS_BETA == 'false' }}