docs(指令檔與 README): 補齊 action 與 workflow 逐行註解並新增專案 README

.gitea/workflows/master.yaml

@@ -1,21 +1,53 @@
+# =============================================================================
+# 用途說明：
+#   本 workflow 為「CD（持續部署）」流程，於程式碼 push 到 master 分支時觸發。
+#   主要工作為 checkout 完整原始碼、依指定 commit 反查其所屬的 git tag，
+#   並將該 tag 輸出顯示，供後續部署或版本追蹤使用。
+# 更新日期：2026/07/03 11:41:20 (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:
+        # 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 }}"