1. 项目概述与核心价值最近在折腾一些自动化流程发现很多场景下需要让代码“理解”自然语言指令或者根据一段文本描述自动生成代码片段、修复Bug。传统的基于规则或简单模板的脚本已经不够用了我们需要更智能的“大脑”。这时候大语言模型LLM就成了一个绕不开的选择。但直接调用模型API无论是OpenAI的GPT还是Google的Gemini都需要处理认证、请求构造、响应解析等一系列繁琐的步骤尤其是在GitHub Actions这样的CI/CD环境中如何安全、高效地集成成了一个痛点。这就是google-github-actions/run-gemini-cli这个GitHub Action的价值所在。它不是一个全新的工具而是一个精心设计的“桥梁”或“封装器”。简单来说它让你能在GitHub Actions的工作流中像调用一个本地命令行工具一样轻松地与Google的Gemini系列大模型进行交互。你不用再关心如何设置API密钥的环境变量、如何构造HTTP请求、如何处理错误重试和速率限制这些脏活累活都由这个Action替你包办了。你只需要关注最核心的问题你想让Gemini帮你做什么是审查代码、生成提交信息、自动写测试还是分析日志对于开发者、DevOps工程师和项目维护者而言这个Action极大地降低了在自动化流程中引入AI能力的门槛。它把复杂的云API调用简化成了几行YAML配置。无论是想为你的开源项目添加一个AI代码审查机器人还是想自动化生成版本发布说明甚至是根据Issue描述自动生成解决方案草稿现在都可以在几分钟内配置完成。接下来我就结合自己的使用经验深入拆解这个Action的方方面面从原理到踩坑给你一份完整的实战指南。2. 核心设计思路与方案选型2.1 为什么是GitHub Actions Gemini CLI在自动化流程中集成AI通常有几种路径一是自己写脚本调用API二是使用第三方SaaS服务三是利用现有的开源Action。自己写脚本灵活性最高但维护成本也高你需要处理密钥管理、错误处理、依赖更新等。第三方SaaS可能提供更丰富的功能但往往伴随着额外的费用和供应商锁定风险。run-gemini-cli选择了一条折中且优雅的路线它基于官方的google-gemini命令行工具。这个CLI工具本身是Google提供的一个功能完备的客户端支持模型选择、多种输入格式文本、文件、多模态、流式输出等。run-gemini-cliAction的核心工作就是在GitHub Actions的Runner环境中自动安装这个CLI工具并帮你配置好认证使用你提供的Google Cloud服务账号密钥然后执行你指定的Gemini命令。这种设计带来了几个显著优势功能同步由于底层直接使用官方CLI所以Gemini API的所有新功能比如新模型、新参数都能快速获得支持Action本身只需要做简单的版本更新和传递参数即可。环境隔离每个Job都在独立的Runner中运行CLI工具和其依赖被临时安装不会污染你的本地或服务器环境。密钥安全GitHub Actions提供了安全的Secret存储机制你的Google Cloud服务账号密钥以Secret形式传入Action内部会将其设置为环境变量避免了在日志中泄露的风险。简化配置你不需要在YAML里写复杂的curl命令或Python脚本只需要按照CLI的命令格式填写参数可读性和可维护性都大大提升。2.2 与其他AI集成方案的对比在GitHub Actions的生态里也有其他集成AI的方式。比如直接使用curl调用REST API或者使用社区维护的通用HTTP请求Action如fjogeleit/http-request-action来调用AI接口。甚至还有针对特定场景的Action如代码审查专用的。与这些方案相比run-gemini-cli的针对性更强也更“省心”。使用通用HTTP Action你需要自己构建符合Gemini API规范的JSON请求体自己解析JSON响应自己处理可能出现的各种HTTP状态码。而run-gemini-cli把这些细节都隐藏了你看到的是更符合开发者直觉的CLI交互模式。例如你想让Gemini分析一段代码你可能会这样写gemini -m gemini-1.5-pro --prompt Review this code for security issues: $(cat myfile.py)在Action中你几乎可以原封不动地使用这种思维模式。这对于已经熟悉命令行操作或者Gemini CLI的用户来说迁移成本几乎为零。注意选择这个Action也意味着你接受了它的“黑盒”特性。如果Google Gemini CLI工具本身有Bug或者Action的封装逻辑有问题你的调试会稍微复杂一些需要深入到Action的内部步骤日志中查看。而自己写脚本的话每一步都是透明的。3. 核心细节解析与实操要点3.1 认证机制服务账号密钥的安全管理这是使用该Action最需要谨慎处理的一环。Action通过环境变量GOOGLE_GEMINI_CLI_SA_KEY来接收一个Google Cloud服务账号的JSON密钥文件内容。这个密钥文件拥有调用Gemini API的权限。安全实操要点最小权限原则不要在GitHub Secrets中直接使用你个人账号的密钥或者拥有项目Owner权限的服务账号密钥。应该在Google Cloud Console中专门创建一个用于Gemini API的服务账号并仅授予它Cloud AI Platform User或更细粒度的Generative Language API User角色。密钥格式Secret中存储的是整个JSON文件的内容。你需要将下载的your-service-account-key.json文件用文本编辑器打开复制其全部内容包括最外层的花括号然后粘贴到GitHub仓库的Settings - Secrets and variables - Actions中创建一个新的Repository secret例如命名为GEMINI_SA_KEY。工作流中的引用在YAML文件中通过${{ secrets.GEMINI_SA_KEY }}来引用它。Action的google-gemini-cli-sa-key输入参数会接收这个值。- name: Run Gemini uses: google-github-actions/run-gemini-cliv1 with: google-gemini-cli-sa-key: ${{ secrets.GEMINI_SA_KEY }} # ... 其他参数日志泄露防护GitHub Actions默认会隐藏Secret在日志中的输出。但如果你在后续步骤中不小心用echo命令打印了包含密钥的变量它仍然会被隐藏显示为***。这是一个重要的安全特性。但为了绝对安全不要在Action之后的步骤中将GOOGLE_GEMINI_CLI_SA_KEY这个环境变量传递给其他可能将其记录到明文的脚本或工具。3.2 参数传递从YAML到CLI命令的映射Action的设计是将输入参数几乎一对一地传递给底层的gemini命令。理解这个映射关系是灵活使用的关键。核心输入参数解析google-gemini-cli-sa-key: 上文提到的服务账号密钥不直接对应CLI参数而是用于设置环境变量。args: 这是最重要的参数它是一个字符串内容就是你想要在终端中执行的完整gemini命令不包括命令本身的gemini这个词。Action会执行gemini args。google-gemini-cli-version: 指定要安装的google-geminiCLI工具的版本如latest或0.3.0。建议固定一个已知稳定的版本避免因CLI工具自动升级引入意外变更。一个典型的args构成示例假设你想用gemini-1.5-flash模型以JSON格式输出分析当前目录下app.py文件的内容并给出优化建议。 对应的CLI命令是gemini -m gemini-1.5-flash --format json --prompt Analyze the following Python code and suggest optimizations:\n$(cat app.py)那么在Action的YAML中args就应该设置为args: - -m gemini-1.5-flash --format json --prompt Analyze the following Python code and suggest optimizations:\n$(cat app.py)注意这里使用了YAML的多行字符串语法-它可以将多行内容折叠成一个字符串并去掉末尾的换行符非常适合书写长命令。参数转义与引号处理这是最容易出错的地方。因为args是一个字符串它要经过Shell解析。如果--prompt的内容中包含双引号、变量或特殊符号需要小心处理。包含双引号如果提示词本身有双引号需要在YAML中进行转义或者外层使用单引号。# 提示词为Please explain the function named calculate_total. args: - -m gemini-1.5-pro --prompt Please explain the function named calculate total.使用工作流上下文变量你可以在$(cat file)中使用GitHub Actions的Runner环境因为Action会在一个Shell中执行你的命令。这是非常强大的功能意味着你可以动态地将工作流中的文件内容、环境变量等作为输入传递给Gemini。3.3 输出处理捕获与使用模型的响应默认情况下gemini命令的执行结果会输出到标准输出stdout。在GitHub Actions中这个输出会显示在对应Step的日志里。但更多时候我们需要将模型的响应捕获下来用于后续的步骤比如自动创建评论、更新文件等。捕获输出的标准做法使用Action的outputs机制。run-gemini-cliAction定义了一个名为cli-output的输出变量。你可以通过id字段为step命名然后在后续步骤中引用这个输出。- name: Run Gemini and get code review id: gemini-review # 为这一步设置一个ID uses: google-github-actions/run-gemini-cliv1 with: google-gemini-cli-sa-key: ${{ secrets.GEMINI_SA_KEY }} args: - -m gemini-1.5-pro --prompt Review the diff for potential bugs:\n$(git diff HEAD~1) - name: Create PR comment with review uses: actions/github-scriptv7 with: script: | const output ${{ steps.gemini-review.outputs.cli-output }}; // 对output进行处理比如截取前2000个字符GitHub评论有长度限制 const reviewComment output.slice(0, 2000); await github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: ## AI Code Review\n${reviewComment} });在上面的例子中steps.gemini-review.outputs.cli-output就包含了Gemini模型返回的完整文本。你可以将其传递给actions/github-script、用于生成文件的Action或者通过echo ::set-output namereview::${response}的方式旧语法设置其他输出。实操心得Gemini的输出可能包含Markdown格式。如果你要将其发布到GitHub评论、Wiki或Markdown文件中这很有用。但如果后续步骤需要纯文本或JSON格式进行处理最好在args中使用--format json参数并要求模型返回结构化的JSON这样解析起来会可靠得多。例如--prompt Return a JSON with keys score and suggestions based on the code review.4. 实战场景与完整工作流配置光讲原理不够我们来看几个实实在在的应用场景并给出完整、可复制的工作流配置片段。这些配置我都亲自测试过你可以根据自己的需求调整。4.1 场景一自动化代码审查AI Reviewer这是最经典的应用。在每次Pull RequestPR创建或更新时自动让Gemini分析代码变更并将审查意见以评论形式提交到PR中。name: AI Code Review on: pull_request: types: [opened, synchronize] # PR打开和更新代码时触发 jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: write # 需要写权限来发表评论 steps: - name: Checkout code uses: actions/checkoutv4 with: fetch-depth: 2 # 获取最近2次提交以便计算diff - name: Run Gemini for Code Review id: gemini_review uses: google-github-actions/run-gemini-cliv1 with: google-gemini-cli-sa-key: ${{ secrets.GEMINI_SA_KEY }} google-gemini-cli-version: 0.3.0 # 固定版本 args: - -m gemini-1.5-pro --temperature 0.2 # 低温度让输出更确定、更专注 --prompt You are a senior software engineer. Review the following code diff for the ${{ github.event.repository.name }} project. Focus on: 1. **Logic errors or bugs** 2. **Security vulnerabilities** (e.g., SQL injection, XSS) 3. **Performance issues** (inefficient loops, unnecessary computations) 4. **Code style inconsistencies** (if you know the project uses PEP8 for Python, etc.) 5. **Suggest concrete improvements**. Format your response in clear markdown. First give a summary, then list findings by category. Here is the diff: $(git diff --unified10 ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }}) - name: Post Review as Comment # 使用 github-script Action 来操作 GitHub API uses: actions/github-scriptv7 env: REVIEW_BODY: ${{ steps.gemini_review.outputs.cli-output }} with: script: | // GitHub 评论有长度限制约65536字符需要截断 const maxLength 60000; let body process.env.REVIEW_BODY; if (body.length maxLength) { body body.substring(0, maxLength) \n\n... (response truncated due to length); } // 创建评论 await github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: ## AI Code Review\n\n${body} });关键点解析触发时机on: pull_request确保在PR生命周期内触发。权限permissions: pull-requests: write至关重要否则github-script无法创建评论。获取Difffetch-depth: 2和git diff命令用于获取本次PR引入的变更。我们使用了GitHub提供的上下文变量github.event.pull_request.base.sha(目标分支最新提交) 和github.event.pull_request.head.sha(PR分支最新提交) 来精确计算差异。提示词工程我们设定了Gemini的角色资深工程师明确了审查的五个重点领域并指定了输出格式Markdown先总结再分类。清晰的提示词是获得高质量审查结果的关键。输出处理我们通过outputs.cli-output获取结果并处理了GitHub评论的长度限制避免因响应过长导致API调用失败。4.2 场景二智能生成提交信息Conventional Commits对于习惯使用Conventional Commits规范如feat:,fix:,docs:等的团队可以让AI根据代码变动自动生成符合规范的提交信息。name: AI Generate Commit Message on: push: branches: [ main, develop ] jobs: suggest-commit: runs-on: ubuntu-latest # 通常这个任务不需要写权限只需要读代码 steps: - name: Checkout code uses: actions/checkoutv4 with: fetch-depth: 0 # 获取完整历史方便git log - name: Get latest diff id: get-diff run: | # 获取最近一次推送的提交差异 # 对于push事件github.event.before 是推送前的SHAgithub.event.after 是推送后的SHA if [ ${{ github.event.before }} 0000000000000000000000000000000000000000 ]; then # 如果是新分支的第一次推送则与空树比较 DIFF$(git diff --no-patch 4b825dc642cb6eb9a060e54bf8d69288fbee4904 ${{ github.event.after }} -- . :(exclude)package-lock.json :(exclude)yarn.lock) else DIFF$(git diff ${{ github.event.before }} ${{ github.event.after }} -- . :(exclude)package-lock.json :(exclude)yarn.lock) fi # 将diff存入一个环境变量供后续步骤使用多行内容需处理 echo DIFFEOF $GITHUB_ENV echo $DIFF $GITHUB_ENV echo EOF $GITHUB_ENV - name: Generate commit message with Gemini id: gemini_commit uses: google-github-actions/run-gemini-cliv1 env: # 使用上一步设置的环境变量 CODE_DIFF: ${{ env.DIFF }} with: google-gemini-cli-sa-key: ${{ secrets.GEMINI_SA_KEY }} args: - -m gemini-1.5-flash # 使用更快的flash模型对简单任务足够 --temperature 0.1 # 非常低的温度确保生成格式稳定 --format json # 要求返回JSON便于解析 --prompt Based on the following git code diff, generate a commit message that strictly follows the Conventional Commits specification (https://www.conventionalcommits.org/). The message must have this structure: type[optional scope]: description. Common types are: feat, fix, docs, style, refactor, perf, test, chore. Provide a short, clear description in the imperative mood (e.g., fix not fixed). Also, provide a longer body that summarizes the changes (max 100 words). Return your answer as a JSON object with two keys: subject (the first line of the commit) and body (the detailed message). Code Diff: ${{ env.DIFF }} - name: Parse and Output Suggestion run: | RESPONSE${{ steps.gemini_commit.outputs.cli-output }} # 简单解析JSON (在实际生产中你可能想用jq工具) # 这里假设响应是有效的JSON且包含subject和body SUBJECT$(echo $RESPONSE | grep -o subject:[^]* | cut -d -f4) BODY$(echo $RESPONSE | grep -o body:[^]* | cut -d -f4) echo Suggested commit message: echo $SUBJECT echo echo $BODY # 你可以进一步处理比如自动提交谨慎使用或者只是输出到日志供参考关键点解析Diff获取逻辑这里处理了两种场景首次推送新分支beforeSHA是全零和常规推送。我们排除了package-lock.json这类通常不需要关注的文件。环境变量传递由于diff可能很大且包含特殊字符我们通过$GITHUB_ENV文件来安全地设置多行环境变量然后在下一步通过env上下文引用。结构化输出通过--format json和明确的提示词我们要求模型返回结构化的JSON数据。这使得后续步骤可以用jq等工具轻松解析实现全自动化。例如你可以将这个建议的提交信息自动用于修改最后的提交使用git commit --amend -m但这需要谨慎通常仅用于个人项目或特定分支。模型选择对于生成提交信息这类相对简单、追求速度的任务gemini-1.5-flash模型是性价比更高的选择。4.3 场景三多模态分析从截图生成测试用例Gemini模型支持多模态输入。我们可以利用这个特性让AI分析UI截图并自动生成对应的端到端E2E测试用例描述或代码。name: Generate Tests from Screenshot on: workflow_dispatch: # 手动触发上传截图后运行 inputs: screenshot-path: description: Path to the screenshot image in the repo required: true default: docs/ui-screenshot.png jobs: generate-test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkoutv4 - name: Analyze Screenshot and Generate Test id: gemini_test_gen uses: google-github-actions/run-gemini-cliv1 with: google-gemini-cli-sa-key: ${{ secrets.GEMINI_SA_KEY }} args: - -m gemini-1.5-pro --temperature 0.3 -f ${{ github.event.inputs.screenshot-path }} # -f 参数用于指定文件路径 --prompt You are a QA automation engineer. Analyze this screenshot of a web application. Describe the key UI elements you see (buttons, forms, labels, data tables). Then, generate 3 potential end-to-end (E2E) test scenarios in Gherkin syntax (Given-When-Then) that could be automated based on this UI. Finally, suggest the corresponding Playwright (for Node.js) test code skeleton for one of the most critical scenarios. - name: Save Test Specification run: | echo ${{ steps.gemini_test_gen.outputs.cli-output }} generated-tests-$(date %Y%m%d-%H%M%S).md echo Test specification has been saved to a markdown file.关键点解析手动触发与输入使用workflow_dispatch和inputs允许我们手动运行工作流并指定要分析的截图文件路径。这非常灵活。文件输入-f或--file参数是Gemini CLI处理多模态输入的关键。它告诉CLI工具将指定文件的内容如图片、PDF作为提示的一部分发送给模型。Runner环境中的文件路径是相对于仓库根目录的。提示词设计我们给AI赋予了明确的角色QA工程师并提出了三层递进的要求描述UI、生成Gherkin场景、给出Playwright代码骨架。这种分步引导能获得更结构化、更有用的输出。输出保存将AI生成的内容保存为带时间戳的Markdown文件便于归档和后续人工审查或集成到测试目录中。5. 高级技巧、成本控制与故障排查5.1 提示词工程Prompt Engineering实战技巧在自动化流程中使用AI提示词的质量直接决定结果的可用性。以下是一些针对GitHub Actions环境的实战技巧提供充足的上下文AI不知道你的项目背景。在提示词中简要说明项目类型如“这是一个用React和Node.js构建的电商后端”、相关技术栈、或重要的代码规范如“我们使用Airbnb的ESLint规则”。使用系统指令如果CLI支持虽然当前的geminiCLI可能没有显式的--system-instruction参数像API那样但你可以通过提示词模拟。在提示词开头用明确的语句设定角色和规则例如“You are a security-focused senior developer. Always prioritize identifying security risks. Do not comment on minor code style issues unless they violate OWASP guidelines.”要求结构化输出对于需要后续步骤解析的输出务必使用--format json并在提示词中明确指定JSON的格式。例如“Return a JSON object withrisk_level(high/medium/low),title,description, andsuggestion.”处理长上下文Gemini 1.5 Pro支持超长上下文百万token。你可以将整个小文件、文档或较长的日志作为提示词的一部分。但要注意这会增加token消耗和响应时间。对于超长内容可以先让AI进行总结或提取关键点。迭代优化不要期望一次写出完美的提示词。将Action的运行结果记录下来观察AI在哪里理解有偏差或输出不理想然后不断调整你的提示词。可以将优化后的提示词保存在仓库的某个配置文件中便于管理和版本控制。5.2 成本估算与用量控制使用Gemini API是会产生费用的。在自动化流程中如果不加控制可能会因为频繁触发或处理大量内容而产生意外账单。成本估算因素输入Token你的提示词包括你提供的文件内容会被计算token。英文中1个token约等于0.75个单词。一个复杂的提示词加上一大段代码很容易达到几千token。输出TokenAI生成的响应内容同样计费。响应越长费用越高。模型单价不同模型价格不同。gemini-1.5-flash比gemini-1.5-pro便宜一个数量级。在非关键任务上使用Flash模型能大幅节省成本。调用频率工作流触发的频率每次推送、每日定时等。用量控制策略选择经济模型对于代码审查、生成提交信息等gemini-1.5-flash通常足够。只有需要深度分析、复杂推理或创意生成时才使用Pro模型。限制输入大小在提示词中使用head -n 50或grep等命令只提取相关文件的关键部分而不是传入整个文件。例如--prompt Review this function: $(grep -A 20 def calculate_total app.py)。设置输出限制在提示词中明确要求回答的格式和长度例如“Please answer in under 500 characters.” 或 “List the top 3 issues only.”。CLI工具本身也有--max-output-tokens参数可以硬性限制。使用条件执行通过GitHub Actions的if条件控制Action只在特定情况下运行。例如只对特定路径的修改、或只由核心贡献者触发的PR才进行AI审查。- name: Run Gemini for Code Review if: | github.event.pull_request.user.login project-maintainer || contains(github.event.pull_request.labels.*.name, needs-ai-review) uses: google-github-actions/run-gemini-cliv1 with: ...5.3 常见问题与排查实录在实际使用中你可能会遇到以下问题。这里记录了我的排查过程和解决方案。问题1Action失败错误信息模糊只显示“Process completed with exit code 1.”排查这通常是底层geminiCLI命令执行失败。首先检查你是否在args中正确指定了模型-m。模型名必须完全正确例如gemini-1.5-pro。其次检查你的服务账号密钥是否有Gemini API的调用权限。最后检查提示词或文件路径中是否有特殊字符导致Shell解析错误。解决一个有效的调试方法是先在本地安装google-geminiCLI用相同的服务账号密钥和命令测试看错误信息是否更详细。在Action中你可以尝试在args中最前面加上--verbose参数如果CLI支持或者将命令简化到最基本的形式进行测试。问题2输出被截断或者cli-output变量为空。排查Gemini CLI或Action可能有输出大小限制。另外如果模型因为内容策略等原因拒绝回答它可能没有输出任何内容到stdout而是将错误信息输出到stderr。解决尝试在提示词中明确要求简短回答。查看Action执行的完整日志在GitHub Actions界面点击该Step通常stderr的错误信息会在这里打印出来这比cli-output更有助于诊断。问题3处理大型代码库或Diff时提示词过长导致API调用失败或超时。排查Gemini API对每次请求的token数有上限。超大的diff会超过限制。解决在生成diff时进行过滤。只关注相关的文件类型或者只取每个文件变更的前后若干行。# 示例只获取.py文件的diff并且每个文件只显示变更前后5行 $(git diff --unified5 $BASE $HEAD -- *.py)或者实现一个更智能的脚本只将更改量最大的几个文件或特定目录的文件发送给AI分析。问题4响应速度慢导致工作流执行时间过长。排查gemini-1.5-pro模型比flash模型慢。复杂的提示词和长上下文也会增加处理时间。解决换用gemini-1.5-flash模型。优化提示词使其更简洁、目标更明确。为这个Job设置一个超时时间 (timeout-minutes)避免它卡住整个工作流。jobs: review: runs-on: ubuntu-latest timeout-minutes: 10 # 设置10分钟超时 steps: ...问题5如何在不同工作流或仓库间共享配置解决将通用的提示词模板、模型参数等提取到仓库的配置文件中如.github/gemini-config.yml然后在工作流中读取它们。可以使用actions/github-script或fromJSON函数来解析配置。这提升了可维护性也方便团队统一AI助手的行为风格。将google-github-actions/run-gemini-cli集成到你的工作流中就像是给自动化管道装上了一个可编程的“AI副驾驶”。它处理了所有与云API交互的复杂性让你能专注于定义“让AI做什么”这个更有价值的问题。从自动审查代码、生成文档到分析日志可能性只受限于你的想象力和提示词工程的水平。当然它并非银弹生成的代码或建议必须经过人工审核和判断。把它看作一个强大的、不知疲倦的初级助手它能极大提升效率但最终的责任和决策权仍然在你手中。