Merge pull request '新增 Antigravity CLI composite action' (#3) from develop into master

Reviewed-on: composite-actions/antigravity#3
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>

.gitea/workflows/cd.yaml

@@ -1,12 +1,29 @@
+# 用途：定義 CD 工作流程，在 master 分支收到 push 時執行版本標籤釋出流程。
+# 更新日期：2026/06/27 23:21:07
+
+# 設定此 Gitea Actions workflow 顯示名稱為 CD，方便在工作流程清單中辨識。
 name: CD
+
+# 定義觸發此 workflow 的事件條件。
 on:
+  # 當程式碼被 push 到指定分支時觸發部署流程。
   push:
+    # 指定只監聽下列分支的 push 事件。
     branches:
+    # 限定 master 分支被推送時才執行 CD workflow。
     - master
+
+# 定義此 workflow 需要執行的所有 job。
 jobs:
+  # 建立負責釋出版本標籤的 job。
   release-tag-version:
+    # 設定 job 在 Gitea Actions 介面中顯示的名稱。
     name: Release Tag Version
+    # 指定此 job 使用 ubuntu runner 執行。
     runs-on: ubuntu
+    # 定義此 job 內依序執行的步驟。
     steps:
+    # 建立釋出並標註成品版本的步驟。
     - name: 釋出並標註成品版本
+      # 呼叫共用 composite action，版本由 ACTION_RELEASE_TAG_VERSION 變數決定。
       uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}

.gitea/workflows/ci.yaml

@@ -1,19 +1,72 @@
+# 用途：在 pull request 更新時執行 CI，先計算測試用版本號，再用該版本呼叫 Antigravity composite action 並驗證輸出內容。
+# 更新日期：2026/06/27 23:21:07
+
+# 定義此 Gitea Actions workflow 顯示的名稱。
 name: CI
+
+# 宣告觸發 workflow 的事件設定。
 on:
+  # 設定 pull request 事件會觸發此 workflow。
   pull_request:
+    # 指定 pull request 目標分支的忽略清單，避免 master 分支觸發此 workflow。
     branches-ignore:
+    # 忽略目標分支為 master 的 pull request。
     - master
+    # 限定只在 pull request 開啟或同步更新時觸發。
     types: [opened, synchronize]
+
+# 定義 workflow 內要執行的 jobs。
 jobs:
-  ai-code-review:
+  # 建立計算 release tag 版本號的 job，供後續測試 job 使用。
-    name: AI Code Review
+  release-tag-version:
+    # 設定版本號 job 在執行介面顯示的名稱。
+    name: Release Tag Version
+    # 指定此 job 在 ubuntu runner 上執行。
     runs-on: ubuntu
-    permissions:
+    # 宣告此 job 對外提供的輸出值。
-      contents: write
+    outputs:
-      pull-requests: write
+      # 將 release-tag-version step 計算出的 version 輸出給需要此 job 的後續 jobs。
-      issues: write
+      version: ${{ steps.release-tag-version.outputs.version }}
+    # 定義版本號 job 的執行步驟。
     steps:
-    - name: AI 程式碼審查 by OpenCode
+    # 呼叫 composite action 計算測試用版本號。
-      uses: https://gitea.jsc.idv.tw/composite-actions/opencode-code-review@${{ vars.ACTION_OPENCODE_CODE_REVIEW_VERSION }}
+    - name: 計算版本號
+      # 設定 step id，讓 job outputs 可以引用此 step 的輸出。
+      id: release-tag-version
+      # 使用內部 release-tag-version action，版本由 repository variable 指定。
+      uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }}
+      # 傳入 release-tag-version action 的參數。
       with:
-        token: ${{ secrets.TOKEN }}
+        # 指定計算 beta 版本號，讓後續測試使用預發版本格式。
+        is_beta: 'true'
+
+  # 建立測試 Antigravity composite action 的 job。
+  antigravity:
+    # 設定 Antigravity 測試 job 在執行介面顯示的名稱。
+    name: Antigravity
+    # 指定此 job 在 ubuntu runner 上執行。
+    runs-on: ubuntu
+    # 宣告此 job 需要先完成版本號 job，才能取得其輸出版本。
+    needs: release-tag-version
+    # 定義 Antigravity 測試 job 的執行步驟。
+    steps:
+    # 使用剛計算出的版本呼叫本 composite action，驗證工具可正常取得模型輸出。
+    - name: 測試工具
+      # 設定 step id，讓後續步驟可以引用此 step 的輸出文字。
+      id: antigravity
+      # 使用本 Antigravity composite action，版本來自前一個 job 的輸出。
+      uses: https://gitea.jsc.idv.tw/composite-actions/antigravity@v${{ needs.release-tag-version.outputs.version }}
+      # 傳入 Antigravity action 所需的輸入參數。
+      with:
+        # 傳入 Antigravity OAuth token secret 參照；此處只保留 secret 名稱引用，不包含 secret 明文。
+        oauth: ${{ secrets.ANTIGRAVITY_OAUTH }}
+        # 傳入 repository variable 指定的 Antigravity 模型名稱。
+        model: ${{ vars.ANTIGRAVITY_MODEL }}
+        # 傳入測試提示詞，要求工具回傳目前登入的 Google 帳號電子郵件。
+        prompt: "請告訴我目前登入的Google帳號，只要電子郵件不要其他任何資訊"
+    # 比對 Antigravity action 的輸出與預期電子郵件，不一致時讓 workflow 失敗。
+    - name: 檢查輸出
+      # 只有在輸出文字不等於預期 repository variable 時才執行失敗指令。
+      if: ${{ steps.antigravity.outputs.text != vars.ANTIGRAVITY_EMAIL }}
+      # 以非零結束碼結束此步驟，讓 CI 明確標示測試失敗。
+      run: exit 1

README.md

@@ -0,0 +1,60 @@
+# Antigravity CLI Composite Action
+
+更新時間：2026/06/27 23:24:37
+
+此 repository 提供一個 Gitea/GitHub Actions composite action，用於安裝 Antigravity CLI、寫入 OAuth token、執行指定提示詞，並將 CLI 輸出寫入 action output。
+
+## 專案列表
+
+### 專案描述
+
+| 專案名稱 | 專案描述 |
+| --- | --- |
+| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/ai-review-resolve/develop-20260627-142726) | 提供 Antigravity CLI composite action，讓 workflow 可透過 `oauth`、`model` 與 `prompt` 輸入執行 CLI 並取得文字輸出。 |
+
+### 參考專案
+
+| 專案名稱 | 參考專案列表 |
+| --- | --- |
+| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/ai-review-resolve/develop-20260627-142726) | 無 |
+
+### NuGet 套件
+
+| 專案名稱 | NuGet 套件列表 |
+| --- | --- |
+| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/ai-review-resolve/develop-20260627-142726) | 無 |
+
+## 功能列表
+
+此 repository 未包含可列入 README 的 public method、public constructor、public extension method 或 public operator。
+
+## 使用範例
+
+### 在 workflow 中呼叫 Antigravity CLI
+
+以下範例示範在 workflow step 中呼叫此 composite action，傳入 OAuth token、模型名稱與提示詞，並在後續步驟讀取 `text` output。
+
+```yaml
+- name: 執行 Antigravity CLI
+  id: antigravity
+  uses: https://gitea.jsc.idv.tw/composite-actions/antigravity@v1
+  with:
+    oauth: ${{ secrets.ANTIGRAVITY_OAUTH }}
+    model: ${{ vars.ANTIGRAVITY_MODEL }}
+    prompt: "請自我介紹"
+
+- name: 使用輸出文字
+  run: printf '%s\n' '${{ steps.antigravity.outputs.text }}'
+```
+
+前置條件：
+
+- `secrets.ANTIGRAVITY_OAUTH` 必須是 Antigravity OAuth token 檔案內容的 base64 字串。
+- `vars.ANTIGRAVITY_MODEL` 必須是 Antigravity CLI 可用的模型名稱。
+- runner 必須可連線到 `https://antigravity.google/cli/install.sh` 以下載 CLI。
+
+預期結果：
+
+- action 會安裝 `agy` CLI。
+- action 會將 OAuth token 寫入 `$HOME/.gemini/antigravity-cli/antigravity-oauth-token` 並設定檔案權限為 `600`。
+- action 會執行 `agy --print "$PROMPT" --model "$MODEL"`，並把 stdout 寫入 `steps.antigravity.outputs.text`。

action.yml

@@ -1,33 +1,95 @@
-name: 'Composite Action Template'
+# 用途：定義可在 GitHub Actions 中使用的 Antigravity CLI composite action，負責安裝 Antigravity CLI、設定 OAuth token、執行提示詞並輸出文字結果。
-description: 'Composite Action 範本'
+# 更新日期：2026/06/27 23:21:07
+
+# 設定 action 顯示名稱，供 workflow 引用與介面顯示。
+name: 'Antigravity CLI'
+# 設定 action 描述，說明此 composite action 提供 Antigravity CLI 工具能力。
+description: 'Antigravity CLI 工具'
+# 設定 action 作者資訊。
 author: 'Jeffery'
+# 宣告此 action 可接收的輸入參數。
 inputs:
-  text:
+  # 定義傳給 Antigravity CLI 的提示詞輸入。
-    description: '輸入的文字'
+  prompt:
+    # 說明 prompt 輸入會被傳遞給 Antigravity CLI。
+    description: '傳給 Antigravity CLI 的提示詞'
+    # 允許呼叫端不提供 prompt，未提供時使用預設值。
     required: false
-    default: 'Hello, World!'
+    # 設定 prompt 的預設提示詞。
+    default: "請自我介紹"
+  # 定義 Antigravity CLI 執行時使用的模型輸入。
+  model:
+    # 說明 model 輸入會指定 Antigravity CLI 使用的模型。
+    description: 'Antigravity CLI 使用的模型'
+    # 要求呼叫端必須提供 model。
+    required: true
+  # 定義 base64 編碼後的 OAuth token 檔案內容輸入。
+  oauth:
+    # 說明 oauth 輸入需提供 base64 編碼的 Antigravity OAuth token 檔案內容；不得在註解或日誌中輸出明文。
+    description: 'base64 編碼的 Antigravity OAuth token 檔案內容'
+    # 要求呼叫端必須提供 OAuth token 內容。
+    required: true
+# 宣告此 action 會輸出的資料。
 outputs:
+  # 定義文字輸出欄位，供後續 workflow step 使用。
   text:
+    # 說明 text 輸出為 Antigravity CLI 回傳的文字。
     description: '輸出的文字'
-    value: ${{ steps.change.outputs.text }}
+    # 將輸出值對應到 antigravity step 寫入的 text output。
+    value: ${{ steps.antigravity.outputs.text }}
+# 宣告 action 的執行方式與步驟。
 runs:
+  # 指定此 action 使用 composite 執行模式。
   using: 'composite'
+  # 定義 composite action 的執行步驟順序。
   steps:
-  - name: 交換
+  # 建立安裝 Antigravity CLI 與設定認證檔案的步驟。
-    id: change
+  - name: 安裝工具
+    # 宣告此步驟需要的環境變數。
     env:
-      GITEA_SERVER_URL: ${{ gitea.server_url }}
+      # 將呼叫端提供的 oauth input 放入 OAUTH 環境變數，供 run 區塊解碼寫入檔案。
-      GITEA_REPOSITORY: ${{ gitea.repository }}
+      OAUTH: ${{ inputs.oauth }}
-      GITEA_TOKEN: ${{ gitea.token }}
+    # 執行 Antigravity CLI 安裝與 OAuth token 檔案建立流程。
-      TEXT: ${{ inputs.text }}
     run: |
-      echo "Gitea Server Url: $GITEA_SERVER_URL"
+      # 下載並執行 Antigravity CLI 安裝腳本，curl 失敗時會因 -f 參數讓指令失敗。
+      curl -fsSL https://antigravity.google/cli/install.sh | bash
+      # 將使用者本機安裝路徑加入 GitHub Actions 後續步驟的 PATH。
+      echo "$HOME/.local/bin" >> "$GITHUB_PATH"
 
-      echo "Gitea Repository: $GITEA_REPOSITORY"
+      # 設定 Antigravity CLI 預期讀取的 OAuth token 檔案路徑。
-
+      oauth_file="$HOME/.gemini/antigravity-cli/antigravity-oauth-token"
-      echo "Gitea Token: $GITEA_TOKEN"
+      # 建立 OAuth token 檔案所在目錄，並限制目錄權限為擁有者可讀寫執行。
-
+      install -d -m 700 "$(dirname "$oauth_file")"
-      echo "Text: $TEXT"
+      # 將 OAUTH 環境變數中的 base64 內容解碼後寫入 token 檔案；此處不輸出 secret 明文。
-
+      printf '%s' "$OAUTH" | base64 -d > "$oauth_file"
-      echo "text=$TEXT" >> "$GITHUB_OUTPUT"
+      # 限制 token 檔案權限為擁有者可讀寫，避免其他使用者讀取。
+      chmod 600 "$oauth_file"
+    # 指定此步驟使用 bash shell 執行。
+    shell: bash
+  # 建立執行 Antigravity CLI 並寫入 action output 的步驟。
+  - name: 執行工具
+    # 設定步驟 id，供 outputs.text 透過 steps.antigravity.outputs.text 取得結果。
+    id: antigravity
+    # 宣告此步驟需要的環境變數。
+    env:
+      # 將呼叫端提供的 model input 放入 MODEL 環境變數。
+      MODEL: ${{ inputs.model }}
+      # 將呼叫端提供的 prompt input 放入 PROMPT 環境變數。
+      PROMPT: ${{ inputs.prompt }}
+    # 執行 Antigravity CLI，列印結果並寫入 GitHub Actions output。
+    run: |
+      # 使用指定提示詞與模型執行 Antigravity CLI，並把標準輸出捕捉到 text 變數。
+      text="$(agy --print "$PROMPT" --model "$MODEL")"
+      # 將 Antigravity CLI 回傳文字輸出到目前步驟日誌。
+      printf '%s\n' "$text"
+      # 開始以 GitHub Actions multiline output 格式寫入 text 輸出。
+      {
+        # 寫入 multiline output 的起始標記。
+        echo 'text<<ANTIGRAVITY_OUTPUT'
+        # 寫入 Antigravity CLI 回傳文字內容。
+        printf '%s\n' "$text"
+        # 寫入 multiline output 的結束標記。
+        echo 'ANTIGRAVITY_OUTPUT'
+      } >> "$GITHUB_OUTPUT"
+    # 指定此步驟使用 bash shell 執行。
     shell: bash