Gemini CLI on GitHub and in CI

The official path: the GitHub Action

Google ships a maintained GitHub Action so you do not script the install yourself. The canonical setup lives in the google-github-actions/run-gemini-cli repository. It wraps the CLI, handles auth, and exposes the prompt and tools as workflow inputs.

You authenticate one of two ways:

• A Gemini API key from Google AI Studio, stored as a GitHub secret. Fastest to start.
• Vertex AI with Workload Identity Federation if you are on Google Cloud and want keyless auth tied to a service account. This is the enterprise path and avoids long-lived secrets entirely. See Vertex AI for the platform side.

For a team repo, prefer the second. For a weekend project, the APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → key is fine.

A workflow that reviews every pull request

Here is a complete, runnable workflow. It triggers when a PR is opened or updated, runs Gemini CLI with a focused review prompt, and is locked down with the permissions and concurrency settings I will explain right after.

That is the whole thing. The run-gemini-cli action does the heavy lifting: it reads the PR context, runs the model against your prompt, and posts the result as a comment using the GITHUB_TOKEN.

A few deliberate choices in that file are worth slowing down for.

Why fetch-depth: 0

By default actions/checkout does a shallow clone with only the latest commit. A reviewer that cannot see the diff against the base branch is useless. Setting fetch-depth: 0 pulls the full history so the CLI can compute and reason over the actual changes.

The prompt is a spec, not a wish

Notice the prompt names exactly three categories and explicitly tells the model to skip style nits. This is the single biggest lever on review quality. A vague prompt ("review this PR") produces noisy, low-trust comments that your team will mute within a week. A scoped prompt produces signal.

Treat the prompt like a code review checklist you would hand a new hire. Name what counts, name what to ignore, and demand citations so a human can verify each claim.

Guardrails: the part people skip

A model that can comment on PRs is mostly harmless. A model that can run arbitrary tools, push commits, or read your secrets is not. CI is exactly where a sloppy setup turns into an incident. Here are the guardrails that matter, in priority order.

1. Least-privilege permissions

The permissions block in the workflow is your first wall. The default GITHUB_TOKEN in many orgs is far more powerful than a reviewer needs.

contents: read lets the action read the code. pull-requests: write lets it comment. Nothing else. The job cannot push to branches, cannot edit workflows, cannot touch releases. If a prompt injection in a malicious PR tried to get the agent to do more, the tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → simply does not have the scope.

2. The fork problem

This is the one that bites teams. The pull_request event from a forked repository runs with a read-only tokentokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition → and no access to secrets, by design, so an attacker cannot open a PR that exfiltrates your GEMINI_API_KEY.

There is a tempting alternative, pull_request_target, which runs in the context of the base repo and does have secrets. Do not reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → for it casually to "fix" reviews on forks. Running untrusted PR code with access to your secrets is the classic GitHub Actions footgun. If you must support forks, gate the job behind a manual labeled trigger so a maintainer reviews the diff before any privileged run.

3. Pin the model and cap the cost

Choose your model tier on purpose. For most PR review work, Gemini Flash is the right call: fast, cheap, and more than capable of catching correctness and security issues in a diff. Reserve Gemini Pro for jobs that need deep multi-file reasoning, like architectural review of a large feature branch.

Combine that with timeout-minutes on the job and cancel-in-progress concurrency (so a force-push does not stack three reviews on one PR) and your spend stays predictable.

4. The model advises, it does not decide

Keep the review as a comment, not a required status check that blocks merges, at least at first. An LLMLLMA Large Language Model is an AI system trained on vast text data to predict and generate language, enabling tasks like writing, summarizing, and answering questions.View full definition → reviewer is an extra pair of eyes, not a gate. If you later promote it to a blocking check, scope that check narrowly (for example, only fail on findings the model labels as security-critical) and keep a human override path.

Beyond review: triage, labels, and slash commands

PR review is the obvious first job, but the same action handles more.

Issue triage on a schedule

Point a scheduled workflow at your open issues and ask the CLI to label and prioritize them. The prompt does the classification, and issues: write permission lets it apply labels. This is genuinely useful on a busy repo where untriaged issues pile up overnight.

On-demand help with a mention

You can trigger the action on issue_comment and have it respond when someone writes @gemini-cli followed by a question. A contributor asks "why does this test fail on Windows?" in a comment, the workflow fires, and Gemini answers inline with context from the repo.

The pattern is the same every time: an event triggers the runner, a scoped prompt plus the right permissions defines what the agent may do, and the output goes back to GitHub. Once you internalize that loop, you can build any of these in an afternoon.

Custom instructions with GEMINI.md

A repo-wide prompt is good. A repo-wide prompt that knows your conventions is better. Gemini CLI reads a GEMINI.md file from your repository as standing context, the same way it does when you run it locally. Drop one at the root and the CI reviewer inherits your house rules without you stuffing them into the workflow YAML.

# Project review guidelines

- This is a TypeScript monorepo. Flag any use of `any`.
- All database calls must go through `src/db/client.ts`. Flag direct queries.
- Public API changes require a changeset file. Flag PRs that add endpoints without one.
- Never suggest disabling ESLint rules to make a check pass.

Now your review prompt can stay short and generic, because the project-specific knowledge lives in version control next to the code it governs. When conventions change, you edit GEMINI.md in a normal PR, and the reviewer that reviews that PR is already following the new rules.

This separation matters: the workflow defines *capability* (what the agent is allowed to do), and GEMINI.md defines *policy* (what good looks like in this codebase). Keep them apart.

Local first, then CI

One workflow habit will save you a lot of failed Actions runs: develop the prompt locally before you commit it. Run Gemini CLI on your own machine against a real branch first.

git checkout feature/payment-retry
gemini -p "Review the diff against main. Focus on correctness, \
security, and error handling. Cite file and line for each finding."

Iterate on the wording until the output is genuinely useful. Only then paste that prompt into the workflow. CI is a slow, awkward place to debug prompt phrasing because every change is a commit and a multi-minute run. Your laptop is instant.

Key Takeaways

• Use the official action. Wire google-github-actions/run-gemini-cli into a pull_request workflow rather than scripting the CLI install yourself, and prefer Vertex AI with Workload Identity Federation over a long-lived APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → key for team repos.
• Scope the prompt like a checklist. Name the few things the reviewer should catch and explicitly tell it to skip the rest. A focused prompt is the difference between a trusted reviewer and noise your team mutes.
• Lock down permissions. Grant only contents: read and pull-requests: write, never reachreach for