run-gemini-cli: wiring Gemini CLI into GitHub Actions

The gap between a chat window and a pull request

Most teams already have an AI assistant somewhere in the loop. The friction is that the assistant sits outside the repository: someone copies a diff into a chat window, pastes the answer back as a comment, and the context goes stale the moment the branch moves. run-gemini-cli closes that gap by running Gemini CLI as a step inside a GitHub Actions workflow, so the agent reads the repository where it lives rather than a pasted excerpt.

The README frames the action as two things at once: an autonomous agent for routine coding tasks and an on-demand collaborator you delegate to. In practice that means a scheduled or event-triggered job that triages a new issue, and a comment handler that responds to `@gemini-cli /review` on an existing pull request. The audience is teams on GitHub Actions who want that behaviour without writing their own Gemini API client. If you are not on GitHub Actions, or you do not want a third-party service reading issue text, this is not the tool for the job.

A dispatcher workflow routes comments to the right job

The architecture is less a service than a set of workflow files. The README describes a Gemini Dispatch workflow that acts as a central dispatcher, routing requests to the appropriate workflow based on the triggering event and the command in the comment. The other three prebuilt workflows (issue triage, pull request review, and a general assistant) are the destinations.

That design has a consequence worth stating plainly: the dispatch workflow is not optional. The README notes that `gemini-dispatch.yml` must also be copied because it triggers the workflows to run. Copy only the review workflow and comment commands will not fire. Underneath, the action invokes Gemini CLI, which is where the model call and the tool-calling actually happen. The README points at the GitHub CLI as the example of a tool the model can drive, which is how the agent reads and writes issue and pull request data. Repository-level customisation comes from a `GEMINI.md` file, which supplies project-specific instructions and context to Gemini CLI. The action itself is a composite action; package.json records `"build": "echo \"No build required for composite action\""`, so there is no compiled artifact to trust beyond the workflow YAML you copy.

Installing it: an API key, a secret, and one command

Setup starts outside GitHub. The README says to obtain an API key from Google AI Studio, then store it as a repository secret named `GEMINI_API_KEY` under Settings > Secrets and variables > Actions. Nothing in the action works without that secret, and the README does not describe a keyless path for the basic quick start.

The README also asks you to add two entries to `.gitignore` before the agent starts committing anything, so local CLI state and credential files do not end up in the repository:

# gemini-cli settings
.gemini/

# GitHub App credentials
gha-creds-*.json

With the secret in place, the recommended path is the setup command rather than copying files by hand. Start Gemini CLI in your terminal and run the slash command:

gemini

/setup-github

The alternative, Option B in the README, is to copy the prebuilt workflows from `examples/workflows` into your repository's `.github/workflows` directory, remembering that `gemini-dispatch.yml` has to come along. After that, opening a pull request should produce an automatic review, and commenting `@gemini-cli /review` on an existing one should trigger the same thing on demand. The README gives `@gemini-cli explain this code change` and `@gemini-cli write unit tests for this component` as examples of the general assistant. If the comment gets no reply, the first thing to check is whether the dispatch workflow is present, since that is the piece the README singles out as required.

Authentication has two separate halves

The README splits authentication into Google Authentication and GitHub Authentication, and that split is the part most likely to cause a confusing failure. Google side, the quick start uses a plain API key. The inputs list also exposes a workload identity path: `gcp_project_id`, `gcp_service_account`, `gcp_workload_identity_provider`, `gcp_location`, and `gcp_token_format`, which defaults to `access_token` and can be set to `id_token`. The README states that `access_token` requires a service account, while an empty string is for direct WIF. If you configure workload identity and leave `gcp_token_format` at its default without a service account, you have mismatched the two halves of that sentence.

`gcp_access_token_scopes` defaults to a comma-separated list covering cloud-platform, userinfo.email and userinfo.profile. Those scopes are broad by default, and the README does not discuss narrowing them. GitHub side, the action needs to comment on issues and pull requests, which is why the examples directory contains a `github-app/` folder and why the `.gitignore` snippet covers `gha-creds-*.json`. Both halves have to be right before a single comment appears.

Where it stops being the right tool

The honest limitation is that this is a language model commenting on your code, and the README does not claim otherwise. It does not describe a deterministic rule engine, a severity threshold, or a way to make a review fail a required check. If your branch protection depends on a review bot that returns a pass or fail status, swapping in a model that writes prose comments changes what your merge gate actually enforces.

Cost and quota are the second boundary. The README points to Google AI Studio for a key "with generous free-of-charge quotas", which is a statement about the free tier at the time of writing, not a guarantee for a busy repository. Every push, every opened issue and every `@gemini-cli` mention is a model call, and a workflow that fires on pull request events on an active repository will make many of them. The README does not document rate-limit handling or a retry budget, so a quota wall is something you discover from failed workflow runs.

Third, the trust boundary is real. Once the workflow runs, the agent has repository access and can drive the GitHub CLI. A prompt injected through an issue body or a pull request description is text the model reads. The README's Best Practices section is the place to look for guidance here, and it does not offer a sandboxing story for the general assistant workflow.

Compared with a static analysis bot

The obvious alternative is a conventional review bot built on linters and static analysis, the kind that posts a fixed set of findings and exits with a status code. The difference in approach is not quality, it is determinism. A linter applies the same rules to the same input every time and can be wired into branch protection; run-gemini-cli applies a model to repository context and produces prose, which is why it can answer `@gemini-cli explain this code change` at all. A linter cannot explain a change, and this action cannot guarantee the same finding twice.

That makes them complements rather than substitutes in most repositories. Keep the linter as the gate and let the Gemini workflow handle triage, first-pass review comments and the explain-this requests that would otherwise land on a maintainer. The README's own framing supports that reading: it describes the action as handling routine coding tasks and on-demand delegation, not as a replacement for existing checks.

Licence, versions and what upkeep looks like

The repository is Apache-2.0, and package.json carries the same identifier. That is a permissive licence with an explicit patent grant, and it is the same licence Google uses across the google-github-actions organisation. Nothing in the README describes a separate commercial tier or a usage restriction beyond whatever terms apply to the Gemini API key you supply. This is a description of the licence file, not legal advice; if you redistribute the workflows or bundle them into a product, read the licence text and the Gemini API terms yourself.

The last push to the default branch was on 2026-08-21, and the most recent tagged release listed is v0.1.22 from 2026-04-24. The version number is still 0.1.x, so treat the workflow interfaces as moving. Upgrades are cheap in the mechanical sense: the action is composite, package.json declares no build step, and the runtime requirement is Node 20 or later with npm 10 or later for anyone working on the repository itself. The cost is in re-reading the example workflows after an upgrade, because the dispatch file is what binds the comment commands to the jobs, and a change there is not something a version bump will surface for you.

Editorial conclusion

Adopt it if your team already runs GitHub Actions and is comfortable giving a Gemini API key to a workflow that can read pull request diffs and issue text, and if you want triage and review to happen without a human pasting a diff into a chat window. Skip it if you need a review gate with deterministic rules, if you cannot store a GEMINI_API_KEY secret, or if your repository already uses a review bot whose checks your branch protection depends on. Before enabling it on a live repository, verify three things: that the gemini-dispatch.yml workflow is present alongside whichever example workflow you copy, that your .gitignore covers .gemini/ and gha-creds-*.json, and that a test pull request produces the review comment you expect before you let it run on the default branch.

Frequently asked questions

Official sources

1. google-github-actions/run-gemini-cli on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases