# =============================================================================
# 用途說明：
#   本 workflow 為「CD（持續部署）」流程，於程式碼 push 到 master 分支時觸發。
#   主要工作為 checkout 完整原始碼、依指定 commit 反查其所屬的 git tag，
#   並將該 tag 輸出顯示，供後續部署或版本追蹤使用。
# 更新日期：2026/07/03 17:43:30 (Asia/Taipei)
# =============================================================================

# workflow 名稱，顯示於 Gitea Actions 介面
name: CD
# 觸發條件設定
on:
  # 監聽 push 事件
  push:
    # 僅限定下列分支
    branches:
    # 只有 push 到 master 分支時才會觸發本 workflow
    - master
# 定義所有工作（jobs）
jobs:
  # 部署工作，job 識別鍵為 deploy
  deploy:
    # 此 job 的顯示名稱
    name: DEPLOY
    # 指定執行環境（runner label）為 ubuntu
    runs-on: ubuntu
    # job 層級環境變數
    env:
      # 取事件 commits 陣列的第二筆（索引 1）之 commit id 作為要處理的 SHA
      # 需人工確認：使用索引 1 而非 0，取的是事件中「第二個」commit；
      #           當一次 push 只包含單一 commit 時，索引 1 可能取不到值（為空）。
      COMMIT_SHA: ${{ gitea.event.commits[1].id }}
    # 依序執行的步驟
    steps:
    # 步驟一：取出原始碼
    - name: Source Code Checkout
      # 使用 actions/checkout，版本由 repo/organization 變數 ACTION_CHECKOUT_VERSION 決定
      uses: actions/checkout@${{ vars.ACTION_CHECKOUT_VERSION }}
      # with：傳入 checkout action 的參數區塊
      with:
        # fetch-depth: 0 代表抓取完整 git 歷史（含所有 tag），
        # 以利後續 git describe 能正確反查 tag（淺層 clone 會導致查不到）。
        fetch-depth: 0
    # 步驟二：取得該 commit 所屬的 tag
    - name: Get Commit Tag
      # 設定步驟 id 為 commit，供後續步驟以 steps.commit.outputs 取得輸出
      id: commit
      # git describe --contains 會找出「包含」指定 commit 的最近 tag，
      # 並將結果以 tag=... 寫入 $GITEA_OUTPUT，成為此步驟的輸出參數 tag。
      run: echo "tag=$(git describe --contains ${{ env.COMMIT_SHA }})" >> $GITEA_OUTPUT
    # 步驟三：顯示取得的 tag
    - name: Show Tag
      # 印出上一步（id=commit）輸出的 tag 值，方便於 log 確認結果
      run: echo "${{ steps.commit.outputs.tag }}"