Hub Google AI CLI 教學

第 5 篇 大師 · 第 13 章

GitHub Action 與 CI

官方 google-github-actions/run-gemini-cli 讓 Gemini CLI 直接成為 workflow step:讀取 PR diff、issue 內容或手動輸入的 prompt,產生摘要、審查意見與分流建議。CI 裡的重點不是把代理放到最大權限,而是把它限制在可追蹤、可失敗、可由人覆核的範圍。

先做版本驗證

Action input、output、Gemini CLI 旗標與驗證方式都可能隨版本改變。上線前請看 action README、Gemini CLI repo、release notes 與你 pin 住的 tag;本章範例中的 @vX.Y.Zgemini_cli_version 都要換成已驗證版本。

13.1 官方 Action 與四個預建 workflow

目前唯一的官方進入點是 google-github-actions/run-gemini-cli,由 Google 官方帳號維護。網路上不少舊教學文章寫的是另一個 repo google-gemini/gemini-cli-action,這個舊版已經被官方封存(archived),文件裡直接稱它是「被取代的原型」。如果你查到的範例用的是舊 repo 名稱,先當作過時教材看待,不要照抄進正式 workflow。

官方在 repo 的 examples/workflows/ 資料夾下準備了四套可以直接抄的範本,各自對應一種常見的自動化需求:

範本資料夾用途
Gemini Dispatchgemini-dispatch中央路由:讀留言指令,決定要轉派給哪一個任務。
Issue Triageissue-triageissue 開啟或重開時自動分類、貼標。
Pull Request Reviewpr-reviewPR 開啟時自動審查程式碼。
Gemini CLI Assistantgemini-assistant@gemini-cli 對話式協作,可以請它寫測試、改程式碼。

最快的安裝方式,是在專案根目錄跑 gemini 進互動模式,輸入 /setup-github,會把上面四套範本自動複製進 .github/workflows/;也可以自己手動從 examples/workflows/ 資料夾把對應的 .yml(與 PR review 附帶的 .toml 審查規則檔)複製過來,兩種做法最後得到的檔案內容相同,差別只在要不要在複製前逐一看過每個檔案。指令的確切互動流程可能隨版本調整,動手前先跑一次 gemini --help 或看當下的官方 README 對一下。

gemini
# 進入互動模式後輸入:
/setup-github

13.2 觸發規則:事件、留言指令與安全放行

PR 開啟會自動觸發 review,issue 開啟或重開會自動觸發 triage,這兩種平常不需要手動下指令。想臨時介入,官方 dispatch workflow 認得留言裡的幾個固定指令:

留言指令動作
@gemini-cli /review手動觸發這則 PR 的審查。
@gemini-cli /triage手動觸發這個 issue 的分類。
@gemini-cli /approve核准,用在需要人工確認才會繼續的流程。
@gemini-cli <任意文字>交給 Gemini CLI Assistant 對話式協作,例如「@gemini-cli 幫我解釋這段變更」。

這些指令能不能真的觸發,還卡著一層身分判斷:dispatch job 會確認留言者身分是 OWNER、MEMBER 或 COLLABORATOR,並且這個 PR 不是來自 fork,兩個條件都成立才會放行執行。這不是 Gemini CLI 特有的機制,是 GitHub Actions 本身「fork PR 拿不到 repository secrets」這項安全設計延伸出來的結果;外部貢獻者的 PR 想要 Gemini review,通常得靠維護者自己在留言區手動 @gemini-cli /review。如果團隊想讓 fork PR 也能自動觸發,要改用 pull_request_target 事件,但這會讓 workflow 用 base repo 的權限去 checkout fork 的程式碼,secrets 外洩風險完全是另一個等級,沒有想清楚配套之前不要為了方便繞過這層防護。

workflow_dispatch 則適合維運者手動輸入 prompt,例如「比較這次 release diff 與 changelog 是否一致」,執行者本來就是有權限的維護者,不用擔心 fork 或身分問題:

name: Gemini manual
on:
  workflow_dispatch:
    inputs:
      prompt:
        description: "交給 Gemini CLI 的任務"
        required: true
        type: string
permissions:
  contents: read

jobs:
  ask:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: gemini
        uses: google-github-actions/run-gemini-cli@vX.Y.Z
        with:
          gemini_cli_version: "x.y.z"
          prompt: ${{ inputs.prompt }}
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
      - run: |
          printf '%s\n' '${{ steps.gemini.outputs.summary }}' >> "$GITHUB_STEP_SUMMARY"

13.3 Prompt、輸出與失敗處理

在 CI 中,prompt 要像規格:說明輸入來源、禁止做什麼、輸出格式、失敗時要回報什麼。把 diff、issue body 或 test log 明確傳入,不要要求模型「自己找所有上下文」。Action 的 summary output 可寫入 GITHUB_STEP_SUMMARY 或 PR comment;error output 則應進 job log 或 artifact,避免吞掉。若 Gemini 只是產生建議,不應直接讓整個 CI 失敗;若它是安全 gate,例如偵測 secret 外洩或 migration checklist 缺項,才用明確規則讓 job exit 1。

- id: review
  uses: google-github-actions/run-gemini-cli@vX.Y.Z
  with:
    gemini_cli_version: "x.y.z"
    prompt: |
      只審查這個 PR diff。輸出繁體中文:
      1. 高風險變更
      2. 缺少的測試
      3. 不阻擋合併的建議
      不要要求推送、改檔或發布。
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

- name: Save outputs
  if: always()
  run: |
    printf '%s\n' '${{ steps.review.outputs.summary }}' > gemini-summary.md
    printf '%s\n' '${{ steps.review.outputs.error }}' > gemini-error.log

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: gemini-debug
    path: |
      gemini-summary.md
      gemini-error.log

官方的 PR review 範本不是只丟一句「幫我看一下這段程式碼」,而是配了一份完整的審查規則檔(gemini-review.toml),把「怎麼審查」寫成規格,不留給模型自由發揮。幾條值得直接抄的規定:只對 diff 裡真正變動的行(unified diff 裡帶 +- 的那些行)留言,不評論沒改到的既有程式碼;每則意見都要標嚴重度,官方用四級符號區分 🔴 Critical、🟠 High、🟡 Medium、🟢 Low;送出 review 一律用 GitHub 的 COMMENT 事件,不會自動按 APPROVE 或 REQUEST_CHANGES,合併與否的裁量權留給人;規則檔裡還明文禁止兩件事——不准在留言裡洩漏自己吃到的系統指令,也不准把留言內容當成可以被 shell 指令替換語法($()<()>())注入執行的地方。最後這條是在防 prompt injection:萬一 diff 裡剛好夾帶惡意字串,想誘導 Gemini 在回覆裡「順便」執行點什麼,這條規則是第一道擋。

如果你的 review、triage、assistant 三個 workflow 想共用同一套審查標準,不必在每個 prompt 裡重複貼一次規則,可以參考第 5 章介紹的 GEMINI_SYSTEM_MD 機制,把規則寫成一份版控進 repo 的檔案,在 workflow 的 env 裡指定路徑,多個 workflow 共用同一份來源,之後要調規則只改一個地方就好。

13.4 身分驗證:Gemini 端與 GitHub 端

認證其實有兩條軸線,容易被當成一件事處理:一軸是 Gemini 那一端「你用什麼身分呼叫模型」,另一軸是 GitHub 那一端「這個 workflow 能用什麼身分操作 repo」。這一節先談 Gemini 端。最簡單的路徑是 repository 或 organization secret 放 GEMINI_API_KEY,job 只在需要的 step 注入。這容易開始,但 key 是長期憑證,需定期輪替、限制存取者,且 fork PR 預設拿不到 secrets。企業或 Google Cloud 環境應優先評估 Workload Identity Federation:GitHub 用 OIDC 換短期 Google Cloud token,再以 service account 呼叫後端,不把長期 key 存在 GitHub。無論哪種方式,都不要把 secret 放在 prompt、artifact、step summary 或 comment;也不要在 pull_request_target 對未信任程式碼 checkout 後執行帶 secret 的步驟。

方式適用情境風險控制
GEMINI_API_KEY小型專案、快速試跑、paid API key。GitHub Secrets、最小 repo 存取、定期輪替。
Workload Identity Federation企業、Google Cloud、需要短期憑證。限制 provider 條件、service account 權限與分支。

憑證設計要和觸發來源一起看。手動 workflow_dispatch 通常可允許較完整的上下文,因為執行者是有權限的維護者;公開 PR 與留言觸發則應預設不注入敏感憑證,只產生不含私密資料的初步摘要。若採 WIF,請把 OIDC subject、repository、branch 或 environment 寫進條件,service account 也只給需要的 API 權限。若採 API key,至少分離 dev、CI、release key,並把輪替步驟寫進 runbook。對高風險 repo,可要求維護者先核准 environment,才讓帶憑證的 job 繼續。發布或部署 job 應只接受受保護分支與完整人工批准,不接受任意留言觸發。

WIF 聽起來設定複雜,官方其實準備了一支一鍵設定腳本,把建立 Workload Identity Pool、Provider、Service Account 這一串手動的 GCP 主控台操作全部自動化:

./scripts/setup_workload_identity.sh --repo "OWNER/REPO" --project "GCP_PROJECT_ID"

跑完之後,把腳本印出的幾個值填進 repo 的 variables(不是 secrets——這些值本身不是機密,真正的機密是背後 OIDC 換出來的短期 token):GCP_WIF_PROVIDER(Workload Identity Provider 資源路徑)、SERVICE_ACCOUNT_EMAIL(代替 workflow 呼叫 API 的服務帳戶)、GOOGLE_CLOUD_PROJECTGOOGLE_CLOUD_LOCATION,以及 GOOGLE_GENAI_USE_VERTEXAI=true 告訴 action 這次要走 Vertex AI 而不是 AI Studio。

WIF 搭配 Gemini Code Assist 容易漏一步

如果走的是 WIF 搭配 Gemini Code Assist(GOOGLE_GENAI_USE_GCA=true)這條路徑,有一步很容易被漏掉:Cloud Code 的 Private API 沒有在 GCP 專案手動啟用的話,會直接失敗。社群 啟用 WIF 之後如果錯誤訊息看起來跟權限或 API 未啟用有關,先去 GCP 主控台確認這個 API 開了沒,而不是先懷疑 Provider 條件設定打錯。

GitHub 端也有兩種身分:GITHUB_TOKEN 與自建 GitHub App

多數情況用 GitHub 自動注入的 GITHUB_TOKEN 就夠,它的權限收斂方式在下一節細講。想要更完整的身分——例如需要觸發別的 workflow、或想讓所有自動化留言都顯示成同一個 bot 帳號,而不是預設的 github-actions[bot]——可以改註冊一個自建的 GitHub App,讓 action 拿這個 App 簽出來的 token 操作:

  • repo variable APP_ID:App 的 ID。
  • repo secret APP_PRIVATE_KEY:整份 .pem 私鑰內容。
  • App 權限至少要開 Contents(Read & write)、Issues(Read & write)、Pull requests(Read & write)。
  • 建立 App 時記得取消勾選 Webhooks 的 Active——這個 App 只是拿來簽發 token,不需要接收事件通知,勾了反而多一個要維護的端點。

13.5 最小權限與工具白名單

GITHUB_TOKEN 預設權限要顯式收斂。PR 摘要只需要 contents: read 與可能的 pull-requests: read;要留言才加 issues: writepull-requests: write;要改檔、push、套 label 都屬於 write action,必須有人審核 workflow、prompt 與觸發條件。安全 gate 應用 deterministic 檢查先擋住明確違規,再讓 Gemini 做解釋或補充建議;不要讓模型單獨決定 deploy、刪除資源、合併 PR 或發布套件。若需要自動修補,建議只產 patch artifact 或開 PR,禁止直接寫 main。

官方 dispatch workflow 的權限寫法值得直接照抄:不是在 workflow 最上層給一組寬鬆權限讓所有 job 共用,而是逐個 job 拆開給——大部分 job 只給 contents: read,真的需要寫入的 job(例如實際執行修改的 plan-execute 類型)才另外給 contents: writeissuespull-requests 的 write 權限也是哪個 job 需要就給哪個 job,不會整份 workflow 一次給滿:

jobs:
  triage:
    permissions:
      contents: read
      issues: write
    steps: [ ... ]

  plan-execute:
    permissions:
      contents: write
      pull-requests: write
    steps: [ ... ]
on:
  issue_comment:
    types: [created]

permissions:
  contents: read
  pull-requests: read
  issues: write

jobs:
  comment-trigger:
    if: contains(github.event.comment.body, '@gemini-cli') && github.event.repository.fork == false
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/run-gemini-cli@vX.Y.Z
        with:
          gemini_cli_version: "x.y.z"
          prompt: "根據這則留言與 PR diff 產生審查摘要;只輸出建議,不改檔。"
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

GITHUB_TOKEN 管得到 GitHub API,管不到 Gemini CLI 自己的工具

permissions 收斂的是這把 token 對 GitHub REST/GraphQL API 能做什麼,這是外層權限。內層還有一組獨立的權限要收:action 的 settings input 接受一段 JSON 字串,會被寫進 .gemini/settings.json,其中 tools.core 可以把這次執行能呼叫的 Gemini CLI 工具收成一份極小清單,甚至能收到「只准跑某一個 shell 指令」這麼細。CI 是無人值守的環境,這層收斂比互動模式更需要認真做,不要把整套工具都開給自動跑的 agent:

- uses: google-github-actions/run-gemini-cli@vX.Y.Z
  with:
    gemini_cli_version: "x.y.z"
    settings: |
      {
        "model": { "maxSessionTurns": 25 },
        "telemetry": { "enabled": true, "target": "local" },
        "tools": { "core": ["list_directory", "read_file", "grep_search", "run_shell_command(echo)"] }
      }

maxSessionTurns 也是同一份 settings 裡值得調的欄位:官方範例把 triage 設在 25 輪、review 預設大約 20 輪,對話式的 assistant 設到 50 輪——輪數上限本質上是任務複雜度的預算,觸發越單純的任務給越少輪,避免一個卡住的 session 把 CI 時間跟 token 一起燒光。另外值得知道:官方 PR review 預設不是把 git diff 文字整段塞進 prompt,而是在背景跑一個 Docker 容器(ghcr.io/github/github-mcp-server)當 MCP Server,讓 Gemini 用 GitHub API 直接讀 diff、直接寫 inline comment。知道這件事,排查會更準:review 完全沒反應時,先確認這個容器有沒有正常啟動,而不是先懷疑 prompt 寫錯——下一節會講一個這裡常見的踩雷狀況。

13.6 已知地雷:資料夾信任、GEMINI.md 與容器化 MCP

這裡三個狀況有個共同特徵:CI 不會像互動模式一樣跳出來問你,只會安靜地用限制模式繼續跑,或者卡住不動,事後很容易被誤判成「設定寫錯」,其實是機制本來就這樣設計。

資料夾信任機制在 CI 裡的完整行為,第 7 章已經講過:checkout 出來的資料夾如果沒被信任,headless 模式不會停下來問,而是直接丟 FatalUntrustedWorkspaceError 結束整個 job。只有 workflow保證只由維護者或已確認可信的協作者觸發,而且 checkout 的內容也在該信任邊界內時,才可在 workflow 明確設置信任。處理公開 issue、fork PR、外部貢獻或任何未信任文字時,不要使用 --skip-trustGEMINI_CLI_TRUST_WORKSPACE=true 來繞過信任檢查;應改用唯讀、最小權限與不載入專案設定的流程。這裡補一段第 7 章沒提到、專屬於 GitHub Actions 情境的插曲:官方自己的範例 workflow 曾經把這個環境變數名稱寫錯,漏掉中間的 CLI,寫成 GEMINI_TRUST_WORKSPACE社群 這種打錯字的設定不會報錯,Gemini CLI 只是讀不到這個變數,行為跟完全沒設一樣,log 裡唯一的線索是一行不太起眼的「Gemini CLI is not running in a trusted directory」。如果你是照抄舊版官方範例卻覺得設定「好像沒生效」,先 grep 一次這個變數的完整拼法;issue #506 已經修正,但網路上流通的舊範例不一定跟著更新。

沒被信任連帶的另一個後果,是 GEMINI.md 這類專案設定會被整套跳過——第 5 章談大型專案怎麼調那節講過本機情境下的同一個根因。CI 情境下更容易被忽略:workflow 通常是全新 runner、全新 checkout,你不會經歷「畫面跳出信任詢問」這個提示,自然也不會想到要去檢查信任狀態,只會覺得「我寫的 GEMINI.md 規則怎麼都沒被套用」。

另一個容易誤判成「整個 action 靜默失敗」的狀況,出在上一節提到的 PR review 專用 Docker 容器:容器有自己獨立的環境,host 端 workflow 的環境變數(例如 REPOSITORYPULL_REQUEST_NUMBER)不會自動穿透進去。社群 症狀是 Gemini 回一句聽起來像它「聽不懂任務」的話:「I need the repository owner, repository name, and the pull request number to proceed」,畫面上完全看不出哪裡出錯,很容易誤以為 action 本身壞了。排查時先確認容器啟動指令有沒有真的用 -eenv: 把這些值傳進去,不要假設容器能看到跟 host 端一樣的環境(issue #265)。

13.7 Debug、版本釘選與 CI 疑難雜症

CI 問題通常發生在三處:權限不夠、secret 沒注入、action/CLI 版本變動。每個 workflow 應記錄 action tag、gemini_cli_version、事件名稱、輸入摘要與 artifact 名稱。debug log 放 artifact,不貼到公開 PR comment。千萬不要在 workflow 裡手動設一個通用的 DEBUG 環境變數——官方文件明講這會讓 Gemini CLI 卡住等一個永遠不會出現的 debugger 來 attach,job 就這樣掛到 timeout。想在 CI 開除錯,改用 --debug 旗標,或設定 action 專用的 GEMINI_DEBUG repo variable,兩者都不會觸發那個等待行為。

版本升級後突然壞掉,是另一個值得先懷疑的方向。0.3.0 之後某個版本出現過一個具體的 base64 解碼錯誤,訊息類似 'contents[3].parts[0].thought_signature' Base64 decoding failed,有使用者因此把 gemini_cli_version 直接釘死在較舊版本(例如 0.2.2)繞過去。社群 action 的 gemini_cli_version input 支援 latestpreviewnightly,也支援指定確切版本號或 git ref;平常追新版沒問題,但哪天 CI 無預警開始報一堆看起來跟這次改動無關的錯誤,第一步不是急著除錯 prompt,是先把版本釘回上一個確定能跑的版本,隔離問題是不是版本升級帶來的。

兩個訊息含糊、不容易一眼定位的錯誤

在自架的 GitHub Enterprise Server 環境,npm install -g @google/gemini-cli@latest 曾經回報安裝失敗、exit code 243;這通常跟企業內網的 npm registry 或 proxy 可達性有關,不是 gemini-cli 本身壞掉,先排除網路層(連不連得到你們內部或外部的 npm registry)再往下查,不要直接懷疑套件版本。另一個常見但線索很少的錯誤是「Exiting due to an error processing the @ command」,多半發生在 prompt 太長、或 @ 檔案引用語法寫錯的時候(issue #266)。社群 排查時與其一直盯著錯誤訊息猜,不如把 prompt 縮到最小可重現的版本,再一步步把 @ 檔案引用加回來,通常比直接讀錯誤訊息更快定位。

CI script 如果要依賴退出碼做分支判斷,第 12 章已經整理過一份退出碼對照表可以先參考。這裡要提醒一件事:非 01 的退出碼(像 4253 這類)在不同官方頁面上的語意記載並不完全一致——有的版本文件把它們對應到 quota/rate limit 類的暫時性錯誤,有的則對應到輸入不合法或對話輪數超過上限這類不該重試的錯誤,兩種語意剛好會讓同一段重試邏輯做出完全相反的判斷。上線前不要照抄任何一份文件(包含這個教學)裡的對照表,自己針對你想處理的失敗情境跑一次、記下 echo $? 的實際數字,比對版本文件更可靠。

Antigravity 過渡提醒

依 Google 公告,2026-06-18 後部分個人 Gemini CLI 路線轉往 Antigravity CLI;CI 不應假設舊登入、quota、模型與帳號政策永久有效。發布 workflow 前,把 action、Gemini CLI、認證方式與產品路線列入版本敏感查核。

13.8 免費配額、Vertex 計費與自架 Enterprise Server

CI 情境對配額特別不友善,原因很單純:dispatch 是事件驅動的,一個 repo 只要同時有好幾個 PR 或 issue 觸發,就是好幾個 job 同時搶同一把 API key 的配額,比人在互動模式裡一次只送一個請求容易撞到限制。免費層的配額這幾年調整得相當頻繁,且方向都是往下修——具體數字變動快,這裡不寫死,發布前務必去官方 rate limits 頁面或當下 AI Studio 主控台核對一次。第 15 章quota 與 rate limit那節有完整的 429 runbook,這裡只強調 CI 場景特有的一個判斷:撞到 429 之後,先分清楚是「暫時排隊」還是「配額被歸零」——後者最常見的線索是錯誤訊息裡出現 limit: 0,代表計費帳戶或 tier 設定本身有問題,純粹等待重試沒有用,得先去確認帳單或 tier 有沒有正確掛上,重試只是浪費 job 時間。

如果 Gemini CLI 已經是正式 CI gate 的一部分,不只是玩票性質的自動留言,13.4 提過的 Vertex AI + WIF 這條路徑除了免長效金鑰,還有一個常被忽略的實務好處:用量計費走 GCP 帳單,不是 AI Studio 的免費層,等於直接繞開前面講的免費配額緊縮問題。免費層適合先驗證流程能不能跑通,正式上線前把認證換到 Vertex AI,是同時解決安全性與穩定性的一步。

自架 GitHub Enterprise Server 的額外功課

官方也支援在自架的 GitHub Enterprise Server(GHES)上跑,但比雲端版 GitHub Actions 多兩件事要處理。第一,workflow 得跑在 self-hosted runner 上,雲端的 ubuntu-latest 連不到你們內網的 GHES。第二,action 呼叫的 API 端點不是寫死指向公開 GitHub,而是透過 GITHUB_SERVER_URL 自動抓取注入,通常不需要手動改,但遇到連線問題,這是第一個該確認的地方。企業內部憑證是比較實際的坑:如果你們的 GHES 掛在內部 CA 簽發的憑證下,要用 NODE_EXTRA_CA_CERTS 指向公司的 CA bundle,讓 Node.js 認得這張憑證;測試階段可以用 NODE_TLS_REJECT_UNAUTHORIZED=0 先繞過驗證,確認其他部分能不能跑,但這只適合排查用,正式環境不要留著這個設定,等於把整個 TLS 驗證關掉。

runs-on: [self-hosted]
env:
  NODE_EXTRA_CA_CERTS: /path/to/corp-ca-bundle.pem

13.9 落實清單與延伸擴充

實作時可把 workflow 分成三層:第一層只收集資料,例如 checkout、列出 diff、讀取 issue body、保存測試 log;第二層呼叫 Gemini,且只給它完成任務所需的最小輸入;第三層才把 summary 寫入 step summary、comment 或 artifact。這樣失敗時能判斷是資料準備、模型呼叫、還是發布結果出問題,也能避免在 prompt 裡混進過多 repo 內容。

PR review prompt 建議固定格式:先說「只根據提供的 diff」,再要求輸出風險等級、證據檔名、缺少的測試與非阻擋建議。Issue triage prompt 則要求分類、重現資訊缺口、建議 label 與回覆草稿。@gemini-cli 觸發要另外檢查留言作者是否為 collaborator、事件是否來自同一 repo、PR 是否來自可信分支;外部 fork 可改成只回覆「請維護者手動執行」。

最後,把 Gemini 的建議當作輔助訊號,而不是唯一裁判。能用 lint、typecheck、unit test、secret scan 或 policy-as-code 判斷的事,先交給 deterministic 工具;Gemini 負責解釋差異、補齊 review checklist、提示風險與產生人工可讀摘要。任何寫入操作都要留下 actor、prompt、版本、輸入摘要與輸出 artifact,讓事後能重跑或追溯。

上線前的最後一哩路,建議先在本機用「跟 CI 一樣的方式」跑一次:用第 12 章介紹過的 gemini -p headless 呼叫方式,把 prompt、輸出格式、退出碼都在自己的終端機跑順,比直接把半成品丟上 GitHub Actions、每次改一點就重新排隊等一輪 workflow 要快得多。確認本機穩定之後,再貼進 workflow。想長期追蹤「這個 repo 的自動化到底燒多少 token」,可以把 action 的 upload_artifacts input 搭配 --session-summary 一起用,把每次執行的 token 用量、延遲、成本寫成 JSON 存成 artifact;累積幾個月下來,就有一份可以畫趨勢圖的用量歷史,比事後回頭猜「這個月帳單為什麼變高」有用得多。

如果團隊已經把 Gemini CLI 用得比較深,官方另外維護一個 gemini-cli-extensions 組織,裡面有現成的 code-review、security 擴充套件,可以透過 action 的 extensions input 傳入 GitHub repo URL 陣列直接安裝進 workflow。security 擴充提供 /security:scan-deps 指令,會拿專案的依賴套件去比對 OSV.dev 弱點資料庫,回報已知漏洞——可以把它當成 Dependabot 或 npm audit 之外多一層交叉驗證,資料源和判斷邏輯都不一樣,不是要取代原本的掃描工具,是多一個角度互相對照。

本章小結

把 Gemini 放進 GitHub Actions,可以先從官方四套範本(Dispatch、Issue Triage、PR Review、Assistant)與 /setup-github 快速安裝開始,接著把觸發條件、雙軸身分驗證(Gemini 端的 API Key/WIF,GitHub 端的 GITHUB_TOKEN/自建 App)、GITHUB_TOKEN 權限與 tools.core 工具白名單這幾層最小權限都收緊。資料夾信任、GEMINI.md 載入、容器化 MCP Server 這幾個地方 CI 不會停下來問你,容易安靜地用限制模式跑或直接卡住,先知道症狀長怎樣,排查會快很多。版本要釘選,退出碼不要照抄任何單一文件,免費配額要用官方頁面現查。任何會寫 issue、改 PR、push branch、套 label 或影響 release 的動作,都應保留人類審核與可追蹤紀錄。

動手試試

  1. 先建立只讀 workflow_dispatch,用手動 prompt 產生 PR 摘要。
  2. summaryerror outputs 存進 artifact,確認不含 secret。
  3. permissions 從全預設改成 job 需要的最小集合,並拆到各個 job 分別給。
  4. 在互動模式跑一次 /setup-github,看看它實際複製了哪些檔案進 .github/workflows/,跟 13.1 的表格對照一下。
  5. 幫其中一個 workflow 加一段 settings input,把 tools.core 收成這個任務真的需要的最小清單。
  6. 記錄 action tag、gemini_cli_version 與 2026-06-18 Antigravity 轉換後的認證路線。