From 0ef85a1f67dcf4731b3008665dd2c52a655d0dcc Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 29 Jun 2026 14:28:06 +0800 Subject: [PATCH] =?UTF-8?q?docs(antigravity):=20=E8=A3=9C=E9=BD=8A=20actio?= =?UTF-8?q?n=20=E8=88=87=20workflow=20=E9=80=90=E8=A1=8C=E8=A8=BB=E8=A7=A3?= =?UTF-8?q?=E4=B8=A6=E9=87=8D=E5=BB=BA=20README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitea/workflows/cd.yaml | 22 ++++++++------- .gitea/workflows/ci.yaml | 26 +++++++++--------- README.md | 16 +++++------ action.yml | 59 +++++++++++++++++++++++----------------- 4 files changed, 67 insertions(+), 56 deletions(-) diff --git a/.gitea/workflows/cd.yaml b/.gitea/workflows/cd.yaml index 678125c..f8dec0c 100644 --- a/.gitea/workflows/cd.yaml +++ b/.gitea/workflows/cd.yaml @@ -1,29 +1,31 @@ -# 用途：定義 CD 工作流程，在 master 分支收到 push 時執行版本標籤釋出流程。 -# 更新日期：2026/06/27 23:21:07 +# 用途：定義 CD（持續部署）工作流程，當 master 分支收到 push 時，執行「版本標籤釋出（release tag）」流程。 +# 更新日期：2026/06/29 14:21:50 -# 設定此 Gitea Actions workflow 顯示名稱為 CD，方便在工作流程清單中辨識。 +# 設定此 Gitea Actions workflow 的顯示名稱為 CD，方便在 Actions 工作流程清單中辨識。 name: CD # 定義觸發此 workflow 的事件條件。 on: - # 當程式碼被 push 到指定分支時觸發部署流程。 + # 監聽 push 事件：當有 commit 被推送到指定分支時觸發。 push: - # 指定只監聽下列分支的 push 事件。 + # 指定只針對下列分支的 push 事件生效。 branches: - # 限定 master 分支被推送時才執行 CD workflow。 + # 限定僅 master 分支被推送時才執行此 CD workflow（避免其他分支誤觸發釋出）。 - master # 定義此 workflow 需要執行的所有 job。 jobs: - # 建立負責釋出版本標籤的 job。 + # 建立負責釋出並標註版本標籤的 job，job id 為 release-tag-version。 release-tag-version: - # 設定 job 在 Gitea Actions 介面中顯示的名稱。 + # 設定此 job 在 Gitea Actions 介面中顯示的名稱。 name: Release Tag Version # 指定此 job 使用 ubuntu runner 執行。 runs-on: ubuntu # 定義此 job 內依序執行的步驟。 steps: - # 建立釋出並標註成品版本的步驟。 + # 步驟：釋出並標註成品版本。 - name: 釋出並標註成品版本 - # 呼叫共用 composite action，版本由 ACTION_RELEASE_TAG_VERSION 變數決定。 + # 呼叫共用的 composite action release-tag-version 來完成版本標籤釋出； + # 使用的 action 版本由 repository variable ACTION_RELEASE_TAG_VERSION 動態決定， + # 可在不改動本檔案的情況下集中切換所引用的 action 版本。 uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }} diff --git a/.gitea/workflows/ci.yaml b/.gitea/workflows/ci.yaml index bf3577f..b40fcc9 100644 --- a/.gitea/workflows/ci.yaml +++ b/.gitea/workflows/ci.yaml @@ -1,5 +1,5 @@ # 用途：在 pull request 更新時執行 CI，先計算測試用版本號，再用該版本呼叫 Antigravity composite action 並驗證輸出內容。 -# 更新日期：2026/06/27 23:21:07 +# 更新日期：2026/06/29 14:21:50 # 定義此 Gitea Actions workflow 顯示的名稱。 name: CI @@ -10,9 +10,9 @@ on: pull_request: # 指定 pull request 目標分支的忽略清單，避免 master 分支觸發此 workflow。 branches-ignore: - # 忽略目標分支為 master 的 pull request。 + # 忽略目標分支為 master 的 pull request（避免正式分支誤觸 CI）。 - master - # 限定只在 pull request 開啟或同步更新時觸發。 + # 限定只在 pull request 開啟（opened）或同步更新（synchronize，即推新 commit）時觸發。 types: [opened, synchronize] # 定義 workflow 內要執行的 jobs。 @@ -23,7 +23,7 @@ jobs: name: Release Tag Version # 指定此 job 在 ubuntu runner 上執行。 runs-on: ubuntu - # 宣告此 job 對外提供的輸出值。 + # 宣告此 job 對外提供的輸出值，讓 needs 此 job 的其他 job 可引用。 outputs: # 將 release-tag-version step 計算出的 version 輸出給需要此 job 的後續 jobs。 version: ${{ steps.release-tag-version.outputs.version }} @@ -33,11 +33,11 @@ jobs: - name: 計算版本號 # 設定 step id，讓 job outputs 可以引用此 step 的輸出。 id: release-tag-version - # 使用內部 release-tag-version action，版本由 repository variable 指定。 + # 使用內部 release-tag-version action，action 版本由 repository variable ACTION_RELEASE_TAG_VERSION 指定（集中管理版本以便升級）。 uses: https://gitea.jsc.idv.tw/composite-actions/release-tag-version@${{ vars.ACTION_RELEASE_TAG_VERSION }} # 傳入 release-tag-version action 的參數。 with: - # 指定計算 beta 版本號，讓後續測試使用預發版本格式。 + # 指定計算 beta 版本號，讓後續測試使用預發（pre-release）版本格式，避免佔用正式 tag。 is_beta: 'true' # 建立測試 Antigravity composite action 的 job。 @@ -46,25 +46,25 @@ jobs: name: Antigravity # 指定此 job 在 ubuntu runner 上執行。 runs-on: ubuntu - # 宣告此 job 需要先完成版本號 job，才能取得其輸出版本。 + # 宣告此 job 需要先完成 release-tag-version job，才能取得其輸出版本（建立執行順序相依）。 needs: release-tag-version # 定義 Antigravity 測試 job 的執行步驟。 steps: # 使用剛計算出的版本呼叫本 composite action，驗證工具可正常取得模型輸出。 - name: 測試工具 - # 設定 step id，讓後續步驟可以引用此 step 的輸出文字。 + # 設定 step id，讓後續步驟可以引用此 step 的輸出文字（steps.antigravity.outputs.text）。 id: antigravity - # 使用本 Antigravity composite action，版本來自前一個 job 的輸出。 + # 使用本 Antigravity composite action，版本來自前一個 job 輸出的 version，前綴 v 組成 release tag。 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 明文。 + # 傳入 Antigravity OAuth token secret 參照；此處只保留 secret 名稱引用，執行時才解析，不包含 secret 明文。 oauth: ${{ secrets.ANTIGRAVITY_OAUTH }} - # 傳入測試提示詞，要求工具回傳目前登入的 Google 帳號電子郵件。 + # 傳入測試提示詞，要求工具回傳目前登入的 Google 帳號電子郵件，作為驗證輸出正確性的依據。 prompt: "請告訴我目前登入的Google帳號，只要電子郵件不要其他任何資訊" # 比對 Antigravity action 的輸出與預期電子郵件，不一致時讓 workflow 失敗。 - name: 檢查輸出 - # 只有在輸出文字不等於預期 repository variable 時才執行失敗指令。 + # 只有在 antigravity step 的輸出文字不等於預期 repository variable（ANTIGRAVITY_EMAIL）時才執行下方失敗指令。 if: ${{ steps.antigravity.outputs.text != vars.ANTIGRAVITY_EMAIL }} - # 以非零結束碼結束此步驟，讓 CI 明確標示測試失敗。 + # 以非零結束碼（exit 1）結束此步驟，讓 CI 明確標示測試失敗。 run: exit 1 diff --git a/README.md b/README.md index 333edd5..57b2c61 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Antigravity CLI Composite Action -更新時間：2026/06/27 23:35:00 +更新時間：2026/06/29 14:21:50 -此 repository 提供一個 Gitea/GitHub Actions composite action，用於安裝 Antigravity CLI、寫入 OAuth token、執行指定提示詞，並將 CLI 輸出寫入 action output。 +此 repository 提供一個 Gitea/GitHub Actions composite action，用於安裝 Antigravity CLI、解碼並寫入 OAuth token、以指定提示詞與模型執行 CLI，並將 CLI 的標準輸出寫入 action output。模型名稱由 action 內部直接讀取 repository variable `vars.ANTIGRAVITY_MODEL`。 ## 專案列表 @@ -10,29 +10,29 @@ | 專案名稱 | 專案描述 | | --- | --- | -| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/ai-review-resolve/develop-20260627-142726) | 提供 Antigravity CLI composite action，讓 workflow 可透過 `oauth` 與 `prompt` 輸入執行 CLI，並從 repository variable 讀取模型名稱後取得文字輸出。 | +| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/develop) | 提供 Antigravity CLI composite action：安裝 `agy` CLI、以 base64 解碼寫入 OAuth token，並以呼叫端的 `prompt` 輸入與 repository variable 指定的模型執行 CLI，最後將文字輸出回傳為 `text` output。 | ### 參考專案 | 專案名稱 | 參考專案列表 | | --- | --- | -| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/ai-review-resolve/develop-20260627-142726) | 無 | +| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/develop) | 無 | ### NuGet 套件 | 專案名稱 | NuGet 套件列表 | | --- | --- | -| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/ai-review-resolve/develop-20260627-142726) | 無 | +| [antigravity](https://gitea.jsc.idv.tw/composite-actions/antigravity/src/branch/develop) | 無 | ## 功能列表 -此 repository 未包含可列入 README 的 public method、public constructor、public extension method 或 public operator。 +此 repository 為 composite action（YAML + bash）專案，未包含可列入 README 的 public method、public constructor、public extension method 或 public operator。 ## 使用範例 ### 在 workflow 中呼叫 Antigravity CLI -以下範例示範在 workflow step 中呼叫此 composite action，傳入 OAuth token 與提示詞，並在後續步驟讀取 `text` output。模型名稱由 action 直接讀取 `vars.ANTIGRAVITY_MODEL`。 +以下範例示範在 workflow step 中呼叫此 composite action，傳入 OAuth token 與提示詞，並在後續步驟讀取 `text` output。模型名稱由 action 直接讀取 `vars.ANTIGRAVITY_MODEL`，呼叫端不需傳入 model。 ```yaml - name: 執行 Antigravity CLI @@ -49,7 +49,7 @@ 前置條件： - `secrets.ANTIGRAVITY_OAUTH` 必須是 Antigravity OAuth token 檔案內容的 base64 字串。 -- `vars.ANTIGRAVITY_MODEL` 必須是 Antigravity CLI 可用的模型名稱。 +- `vars.ANTIGRAVITY_MODEL` 必須是 Antigravity CLI 可用的模型名稱（未設定時 action 會直接失敗）。 - runner 必須可連線到 `https://antigravity.google/cli/install.sh` 以下載 CLI。 預期結果： diff --git a/action.yml b/action.yml index f1c04b1..f5c0c14 100644 --- a/action.yml +++ b/action.yml @@ -1,5 +1,8 @@ -# 用途：定義可在 GitHub Actions 中使用的 Antigravity CLI composite action，負責安裝 Antigravity CLI、設定 OAuth token、執行提示詞並輸出文字結果。 -# 更新日期：2026/06/27 23:35:00 +# 用途：定義可在 GitHub/Gitea Actions 中使用的 Antigravity CLI composite action， +# 負責安裝 Antigravity CLI、解碼並寫入 OAuth token、以指定提示詞與模型執行 CLI， +# 並把標準輸出回傳為 action 的 text output。模型名稱由 action 內部讀取 +# repository variable（vars.ANTIGRAVITY_MODEL），不再透過 input 傳入。 +# 更新日期：2026/06/29 14:21:50 # 設定 action 顯示名稱，供 workflow 引用與介面顯示。 name: 'Antigravity CLI' @@ -13,19 +16,19 @@ inputs: prompt: # 說明 prompt 輸入會被傳遞給 Antigravity CLI。 description: '傳給 Antigravity CLI 的提示詞' - # 允許呼叫端不提供 prompt，未提供時使用預設值。 + # 允許呼叫端不提供 prompt，未提供時使用下方預設值。 required: false - # 設定 prompt 的預設提示詞。 + # 設定 prompt 的預設提示詞，避免呼叫端未帶 prompt 時 CLI 缺少輸入。 default: "請自我介紹" - # 定義 base64 編碼後的 OAuth token 檔案內容輸入。 + # 定義 base64 編碼後的 OAuth token 檔案內容輸入（屬於 secret，請以 secrets 傳入）。 oauth: - # 說明 oauth 輸入需提供 base64 編碼的 Antigravity OAuth token 檔案內容；不得在註解或日誌中輸出明文。 + # 說明 oauth 輸入需提供 base64 編碼的 Antigravity OAuth token 檔案內容；此為敏感憑證，不得在註解、echo 或日誌中輸出明文。 description: 'base64 編碼的 Antigravity OAuth token 檔案內容' - # 要求呼叫端必須提供 OAuth token 內容。 + # 要求呼叫端必須提供 OAuth token 內容，缺少時 action 無法通過認證。 required: true # 宣告此 action 會輸出的資料。 outputs: - # 定義文字輸出欄位，供後續 workflow step 使用。 + # 定義文字輸出欄位，供後續 workflow step 透過 steps..outputs.text 使用。 text: # 說明 text 輸出為 Antigravity CLI 回傳的文字。 description: '輸出的文字' @@ -33,62 +36,68 @@ outputs: value: ${{ steps.antigravity.outputs.text }} # 宣告 action 的執行方式與步驟。 runs: - # 指定此 action 使用 composite 執行模式。 + # 指定此 action 使用 composite 執行模式（由多個 step 組成）。 using: 'composite' # 定義 composite action 的執行步驟順序。 steps: - # 建立安裝 Antigravity CLI 與設定認證檔案的步驟。 + # 建立安裝 Antigravity CLI 與設定 OAuth 認證檔案的步驟。 - name: 安裝工具 # 宣告此步驟需要的環境變數。 env: - # 將呼叫端提供的 oauth input 放入 OAUTH 環境變數，供 run 區塊解碼寫入檔案。 + # 將呼叫端提供的 oauth input 放入 OAUTH 環境變數，供 run 區塊解碼寫入檔案； + # 透過 env 傳遞（而非直接內插到 run 字串）可避免 secret 明文出現在指令中。 OAUTH: ${{ inputs.oauth }} # 執行 Antigravity CLI 安裝與 OAuth token 檔案建立流程。 run: | - # 下載並執行 Antigravity CLI 安裝腳本，curl 失敗時會因 -f 參數讓指令失敗。 + # 下載並以 bash 執行 Antigravity CLI 官方安裝腳本； + # curl -f 在 HTTP 錯誤時回傳非零，-sSL 為安靜模式並跟隨重導向，下載失敗時 pipeline 會中止。 curl -fsSL https://antigravity.google/cli/install.sh | bash - # 將使用者本機安裝路徑加入 GitHub Actions 後續步驟的 PATH。 + # 將安裝後 CLI 所在的使用者本機路徑寫入 $GITHUB_PATH， + # 使後續步驟的 PATH 能找到 agy 指令。 echo "$HOME/.local/bin" >> "$GITHUB_PATH" # 設定 Antigravity CLI 預期讀取的 OAuth token 檔案路徑。 oauth_file="$HOME/.gemini/antigravity-cli/antigravity-oauth-token" - # 建立 OAuth token 檔案所在目錄，並限制目錄權限為擁有者可讀寫執行。 + # 建立 OAuth token 檔案所在目錄，並限制目錄權限為擁有者可讀寫執行（700），避免他人存取。 install -d -m 700 "$(dirname "$oauth_file")" - # 將 OAUTH 環境變數中的 base64 內容解碼後寫入 token 檔案；此處不輸出 secret 明文。 + # 將 OAUTH 環境變數中的 base64 內容解碼後寫入 token 檔案； + # 使用 printf 直寫不經 echo 額外換行，且全程不得輸出 secret 明文（勿加 set -x 或 echo "$OAUTH"）。 printf '%s' "$OAUTH" | base64 -d > "$oauth_file" - # 限制 token 檔案權限為擁有者可讀寫，避免其他使用者讀取。 + # 限制 token 檔案權限為擁有者可讀寫（600），避免其他使用者讀取憑證。 chmod 600 "$oauth_file" # 指定此步驟使用 bash shell 執行。 shell: bash # 建立執行 Antigravity CLI 並寫入 action output 的步驟。 - name: 執行工具 - # 設定步驟 id，供 outputs.text 透過 steps.antigravity.outputs.text 取得結果。 + # 設定步驟 id 為 antigravity，供上方 outputs.text 透過 steps.antigravity.outputs.text 取得結果。 id: antigravity # 宣告此步驟需要的環境變數。 env: - # 從 repository variable 讀取 Antigravity CLI 使用的模型名稱。 + # 從 repository variable 讀取 Antigravity CLI 使用的模型名稱（取代舊有的 model input）。 MODEL: ${{ vars.ANTIGRAVITY_MODEL }} - # 將呼叫端提供的 prompt input 放入 PROMPT 環境變數。 + # 將呼叫端提供的 prompt input 放入 PROMPT 環境變數，避免直接內插造成的引號/注入問題。 PROMPT: ${{ inputs.prompt }} # 執行 Antigravity CLI，列印結果並寫入 GitHub Actions output。 run: | - # 確認呼叫端 repository 已設定 ANTIGRAVITY_MODEL variable。 + # 前置檢查：確認呼叫端 repository 已設定 ANTIGRAVITY_MODEL variable，未設定則明確報錯並中止， + # 避免以空模型名稱呼叫 CLI 而產生不明確的失敗。 if [ -z "$MODEL" ]; then echo 'ANTIGRAVITY_MODEL repository variable is required.' >&2 exit 1 fi - # 使用指定提示詞與模型執行 Antigravity CLI，並把標準輸出捕捉到 text 變數。 + # 使用指定提示詞與模型執行 Antigravity CLI（agy --print 為一次性輸出模式）， + # 並以命令替換把標準輸出捕捉到 text 變數。 text="$(agy --print "$PROMPT" --model "$MODEL")" - # 將 Antigravity CLI 回傳文字輸出到目前步驟日誌。 + # 將 Antigravity CLI 回傳文字輸出到目前步驟日誌，方便檢視結果。 printf '%s\n' "$text" - # 開始以 GitHub Actions multiline output 格式寫入 text 輸出。 + # 以群組指令一次性將 text 寫入 $GITHUB_OUTPUT，採用 multiline output 格式以支援多行內容。 { - # 寫入 multiline output 的起始標記。 + # 寫入 multiline output 的起始標記（heredoc 風格的結束符為 ANTIGRAVITY_OUTPUT）。 echo 'text<> "$GITHUB_OUTPUT" # 指定此步驟使用 bash shell 執行。