run-gemini-cli

概述

run-gemini-cli 是一个 GitHub Action，通过 Gemini CLI 将 Gemini 集成到您的开发工作流中。它既可以作为关键常规编码任务的自主代理，也可以作为可随时委派工作的按需协作伙伴。

使用它可以在您的 GitHub 仓库内直接以对话式的方式（例如 @gemini-cli 解决这个问题）执行 GitHub 拉取请求审查、问题分类、代码分析和修改等操作。

• run-gemini-cli
  • 概述
  • 功能
  • 快速入门
    • 1. 获取 Gemini API 密钥
    • 2. 将其添加为 GitHub 秘密
    • 3. 更新 .gitignore 文件
    • 4. 选择工作流
    • 5. 试用一下！
  • 工作流
    • Gemini 分发
    • 问题分类
    • 拉取请求审查
    • Gemini CLI 助手
  • 配置
    • 输入
    • 输出
    • 仓库变量
    • 秘密
  • 身份验证
    • Google 身份验证
    • GitHub 身份验证
  • 可观测性
  • 扩展
  • 最佳实践
  • 自定义
  • 贡献

功能

• 自动化：根据事件（如问题打开）或计划（如每晚）触发工作流。
• 按需协作：通过在问题和拉取请求评论中提及 Gemini CLI 来触发工作流（例如 @gemini-cli /review）。
• 工具扩展性：利用 Gemini 模型的工具调用能力与其他 CLI（如 GitHub CLI (gh)) 进行交互。
• 可定制：在您的仓库中使用 GEMINI.md 文件，为 Gemini CLI 提供项目特定的指令和上下文。

快速入门

只需几分钟即可在您的仓库中开始使用 Gemini CLI：

1. 获取 Gemini API 密钥

从 Google AI Studio 获取您的 API 密钥，享受丰厚的免费配额。

2. 将其添加为 GitHub 秘密

将您的 API 密钥存储为名为 GEMINI_API_KEY 的仓库秘密：

• 前往您的仓库的 设置 > 秘密和变量 > Actions
• 点击 新建仓库秘密
• 名称：GEMINI_API_KEY，值：您的 API 密钥

3. 更新 .gitignore 文件

将以下条目添加到您的 .gitignore 文件中：

# gemini-cli 设置
.gemini/

# GitHub 应用程序凭据
gha-creds-*.json

4. 选择工作流

您有两种方式来设置工作流：

选项 A：使用设置命令（推荐）

1. 在终端中启动 Gemini CLI：

   gemini
   

2. 在终端中的 Gemini CLI 中输入：

   /setup-github
   

选项 B：手动复制工作流

1. 将预构建的工作流从 examples/workflows 目录复制到您仓库的 .github/workflows 目录中。注意：必须同时复制 gemini-dispatch.yml 工作流，该工作流会触发其他工作流的运行。

5. 试用一下！

拉取请求审查：

• 在您的仓库中打开一个拉取请求，并等待自动审查。
• 在现有拉取请求上评论 @gemini-cli /review 以手动触发审查。

问题分类：

• 打开一个问题并等待自动分类。
• 在现有问题上评论 @gemini-cli /triage 以手动触发分类。

通用 AI 协助：

• 在任何问题或拉取请求中，提及 @gemini-cli 并附上您的请求。
• 示例：
  • @gemini-cli 解释这个代码更改
  • @gemini-cli 为这个函数提出改进建议
  • @gemini-cli 帮我调试这个错误
  • @gemini-cli 为这个组件编写单元测试

工作流

此操作提供了多个针对不同用例的预构建工作流。每个工作流都设计为复制到您仓库的 .github/workflows 目录中，并根据需要进行自定义。

Gemini 分发

此工作流充当 Gemini CLI 的中央调度器，根据触发事件和评论中提供的命令，将请求路由到相应的工作流。有关如何设置分发工作流的详细指南，请参阅 Gemini 分发工作流文档。

问题分类

此操作可用于自动或按计划对 GitHub 问题进行分类。有关如何设置问题分类系统的详细指南，请参阅 GitHub 问题分类工作流文档。

拉取请求审查

此操作可在拉取请求打开时自动对其进行审查。有关如何设置拉取请求审查系统的详细指南，请参阅 GitHub PR 审查工作流文档。

Gemini CLI 助手

此类操作可用于在拉取请求和问题中调用通用的对话式 Gemini AI 助手，以执行各种任务。有关如何设置通用 Gemini CLI 工作流的详细指南，请参阅 Gemini 助手工作流文档。

配置

输入

• gcp_location: (可选) Google Cloud 地区。

• gcp_project_id: (可选) Google Cloud 项目 ID。

• gcp_service_account: (可选) Google Cloud 服务账号邮箱。

• gcp_workload_identity_provider: (可选) Google Cloud 工作负载身份提供商。

• gcp_token_format: (可选，默认值：access_token) 用于身份验证的令牌格式。设置为 access_token 可生成访问令牌（需要服务账号），或设置为空字符串以直接使用 WIF。可取值为 access_token 或 id_token。

• gcp_access_token_scopes: (可选，默认值：https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,https://www.googleapis.com/auth/userinfo.profile) 当 token_format 设置为 access_token 时使用的访问令牌范围。以逗号分隔的 OAuth 2.0 范围列表。

• gemini_api_key: (可选) Gemini API 的 API 密钥。

• gemini_cli_version: (可选，默认值：latest) 要安装的 Gemini CLI 版本。可取值为 latest、preview、nightly、特定版本号，或 Git 分支、标签、提交哈希。更多信息请参阅 Gemini CLI 发布说明。

• gemini_debug: (可选) 启用调试日志记录和输出流式传输。

• gemini_model: (可选) 与 Gemini 配合使用的模型。

• google_api_key: (可选) 与 Gemini 搭配使用的 Vertex AI API 密钥。

• prompt: (可选，默认值：You are a helpful assistant.) 传递给 Gemini CLI 的 --prompt 参数 的字符串。

• settings: (可选) 写入 .gemini/settings.json 的 JSON 字符串，用于配置 CLI 的 项目 设置。 更多详情请参阅关于 设置文件 的文档。

• use_gemini_code_assist: (可选，默认值：false) 是否使用 Code Assist 来访问 Gemini 模型，而不是使用默认的 Gemini API 密钥。 更多信息请参阅 Gemini CLI 文档。

• use_vertex_ai: (可选，默认值：false) 是否使用 Vertex AI 来访问 Gemini 模型，而不是使用默认的 Gemini API 密钥。 更多信息请参阅 Gemini CLI 文档。

• extensions: (可选) 要安装的 Gemini CLI 扩展列表。

• upload_artifacts: (可选，默认值：false) 是否将构建产物上传到 GitHub Actions。

• use_pnpm: (可选，默认值：false) 是否使用 pnpm 而不是 npm 来安装 gemini-cli。

• workflow_name: (可选，默认值：${{ github.workflow }}) GitHub 工作流名称，用于遥测目的。

输出

• summary: Gemini CLI 执行后的汇总输出。

• error: Gemini CLI 执行过程中产生的错误输出（如有）。

仓库变量

我们建议将以下值设置为仓库变量，以便在所有工作流中重复使用。或者，您也可以在单个工作流中将其作为操作输入内联设置，或覆盖仓库级别的值。

名称	描述	类型	必需	需要时
GEMINI_DEBUG	启用 Gemini CLI 的调试日志记录。	变量	否	永不
GEMINI_CLI_VERSION	控制安装哪个版本的 Gemini CLI。	变量	否	锁定 CLI 版本
GCP_WIF_PROVIDER	工作负载身份提供商的完整资源名称。	变量	否	使用 Google Cloud
GOOGLE_CLOUD_PROJECT	用于推理和可观测性的 Google Cloud 项目。	变量	否	使用 Google Cloud
SERVICE_ACCOUNT_EMAIL	Google Cloud 服务账户的电子邮件地址。可选——仅在使用服务账户 WIF 时需要（直接 WIF 不需要）。	变量	否	使用服务账户 WIF
GOOGLE_CLOUD_LOCATION	Google Cloud 项目的区域。	变量	否	使用 Google Cloud
GOOGLE_GENAI_USE_VERTEXAI	设置为 true 以使用 Vertex AI	变量	否	使用 Vertex AI
GOOGLE_GENAI_USE_GCA	设置为 true 以使用 Gemini Code Assist	变量	否	使用 Gemini Code Assist
APP_ID	自定义身份验证的 GitHub 应用程序 ID。	变量	否	使用自定义 GitHub 应用程序

[!WARNING] 请勿使用 DEBUG 环境变量，因为它会导致 Gemini CLI 挂起，等待节点调试器连接。

添加仓库变量的步骤：

1. 前往您的仓库的 设置 > 秘密和变量 > Actions > 新建变量。
2. 输入变量名和值。
3. 保存。

有关仓库变量的详细信息，请参阅 GitHub 关于变量的文档。

秘密

您可以在仓库中设置以下秘密：

名称	描述	必需	需要时
GEMINI_API_KEY	您来自 Google AI Studio 的 Gemini API 密钥。	否	您没有 GCP 项目。
APP_PRIVATE_KEY	您 GitHub 应用程序的私钥（PEM 格式）。	否	使用自定义 GitHub 应用程序。
GOOGLE_API_KEY	您用于 Vertex AI 的 Google API 密钥。	否	您拥有 Express Vertex AI 账户。

添加秘密的步骤：

1. 前往您的仓库的 设置 > 秘密和变量 > Actions > 新建仓库秘密。
2. 输入秘密名称和值。
3. 保存。

有关更多信息，请参阅 GitHub 官方关于创建和使用加密秘密的文档。

身份验证

此操作需要同时对 Google 服务（用于 Gemini AI）和 GitHub API 进行身份验证。

Google 身份验证

请选择最适合您用例的身份验证方法：

1. Gemini API 密钥： 对于不需要 Google Cloud 集成的项目来说，这是最简单的方法。
2. 工作负载身份联合： 这是向 Google Cloud 服务进行身份验证的最安全方法。

GitHub 身份验证

您可以通过两种方式对 GitHub 进行身份验证：

1. 默认 GITHUB_TOKEN： 对于更简单的用例，该操作可以使用工作流提供的默认 GITHUB_TOKEN。
2. 自定义 GitHub 应用程序（推荐）： 为了获得最安全、最灵活的身份验证，我们建议创建一个自定义 GitHub 应用程序。

有关 Google 和 GitHub 身份验证的详细设置说明，请参阅 身份验证文档。

观测性

此操作可以配置为将遥测数据（跟踪、指标和日志）发送到您自己的 Google Cloud 项目。这使您能够监控 Gemini CLI 在工作流中的性能和行为，从而为调试和优化提供有价值的见解。

有关如何设置和配置观测性的详细说明，请参阅 观测性文档。

扩展

Gemini CLI 可以通过扩展来增加额外的功能。这些扩展是从其 GitHub 仓库的源代码安装的。

有关如何设置和配置扩展的详细说明，请参阅 扩展文档。

最佳实践

为确保自动化工作流的安全性、可靠性和效率，我们强烈建议遵循我们的最佳实践。这些指南涵盖了仓库安全、工作流配置和监控等关键领域。

主要建议包括：

• 保护您的仓库： 实施分支和标签保护，并限制拉取请求的批准者。
• 工作流配置： 使用工作负载身份联合实现对 Google Cloud 的安全身份验证，有效管理秘密，并锁定操作版本以防止意外更改。
• 监控和审计： 定期审查操作日志，并启用 OpenTelemetry 以深入了解性能和行为。

有关保护仓库和工作流的全面指南，请参阅我们的 最佳实践文档。

自定义

在您的仓库根目录下创建一个 GEMINI.md 文件，以向 Gemini CLI 提供项目特定的上下文和说明。这对于定义编码规范、架构模式或其他模型应遵循的指导原则非常有用。

贡献

欢迎贡献！请查看 Gemini CLI 的 贡献指南，了解更多关于如何开始的信息。

run-gemini-cli 快速上手指南

run-gemini-cli 是一个 GitHub Action，可将 Google Gemini AI 集成到您的开发工作流中。它既能作为自动代理处理代码审查、问题分类等常规任务，也能作为按需协作助手，通过评论直接与您互动。

环境准备

在开始之前，请确保满足以下条件：

• GitHub 仓库：拥有权限管理的 GitHub 仓库。
• Gemini API Key：需要从 Google AI Studio 获取 API 密钥。
  • 访问 Google AI Studio 登录并创建密钥（通常包含免费的试用额度）。
  • 注意：由于网络原因，国内开发者访问 Google 服务可能需要配置代理或使用特定的网络环境。
• 本地终端（可选）：如果希望使用命令行辅助设置工作流，需在本地安装 Node.js 和 npm/pnpm。

安装步骤

1. 配置 GitHub Secret

将获取到的 API Key 安全地存储在 GitHub 仓库中：

1. 进入仓库页面，点击 Settings (设置)。
2. 在左侧菜单选择 Secrets and variables > Actions。
3. 点击 New repository secret (新建仓库密钥)。
4. 填写以下信息：
   • Name: GEMINI_API_KEY
   • Value: 粘贴您的 Gemini API Key
5. 点击 Add secret 保存。

2. 更新 .gitignore

为了防止敏感凭证和临时文件被提交到代码库，请在项目根目录的 .gitignore 文件中添加以下内容：

# gemini-cli settings
.gemini/

# GitHub App credentials
gha-creds-*.json

3. 设置工作流 (Workflow)

您有两种方式将工作流引入仓库：

方案 A：使用命令行自动设置（推荐）

如果您本地已安装 Gemini CLI，可以使用内置命令自动生成配置文件：

1. 在终端启动 Gemini CLI：

   gemini
   

2. 在交互式界面中输入以下命令：

   /setup-github
   

   该命令会自动将必要的 workflow 文件复制到您的 .github/workflows 目录。

方案 B：手动复制工作流文件

如果不使用命令行，可手动从官方示例中复制：

1. 从 examples/workflows 目录下载所需的 workflow 文件（如 gemini-dispatch.yml, pr-review.yml 等）。
2. 将它们上传到您仓库的 .github/workflows/ 目录下。
   • 重要：必须包含 gemini-dispatch.yml，它是路由其他请求的核心分发器。

基本使用

配置完成后，无需额外部署即可在 GitHub 上使用。

1. 自动触发

• PR 审查：创建新的 Pull Request 后，Action 会自动运行并进行代码审查。
• 问题分类：新建 Issue 时，系统会自动进行初步分析和分类。

2. 按需交互 (Comment Trigger)

在任意 Issue 或 Pull Request 的评论区提及 @gemini-cli 并跟随指令即可触发任务：

• 代码审查：

  @gemini-cli /review
  

• 问题分类：

  @gemini-cli /triage
  

• 通用辅助：

  @gemini-cli explain this code change
  @gemini-cli suggest improvements for this function
  @gemini-cli help me debug this error
  @gemini-cli write unit tests for this component
  

AI 将在评论区直接回复分析结果或建议。