Gemini CLI auf GitHub und in CI

Sie kkDie durchschnittliche Zahl neuer Nutzer, die jeder bestehende Nutzer über Empfehlungen generiert. Über 1,0 verstärkt sich das Wachstum selbst und wird exponentiell.Vollständige Definition ansehen →önnen Gemini jeden Pull Request lesen lassen, den Ihr Team öffnet, ein strukturiertes Review hinterlassen und dabei nie einen Browser-Tab öffnen. Das ist das Versprechen, wenn Sie Gemini CLI innerhalb von GitHub Actions ausführen: dieselbe agentische CLI, die Sie lokal nutzen, jetzt ausgelöst durch Repository-Events und begrenzt durch die Guardrails, die Sie setzen.

In dieser Lektion geht es darum, das sauber zu verdrahten. Keine Demo, die „looks good to me“ postet, sondern ein Reviewer, der in CI läuft, Least Privilege respektiert und laut scheitert, wenn etwas nicht stimmt.

Warum die CLI und nicht nur Code Assist

Sie kennen Gemini Code Assist bereits als IDE-Begleiter, der Code vervollständigt und Fragen in Ihrem Editor beantwortet. Das läuft dort, wo ein Mensch tippt.

Gemini CLI unterscheidet sich in einem Punkt, der hier zählt: Es ist ein headless, skriptbarer Agent. ErErDas Verhältnis von Interaktionen (Likes, Kommentare, Shares) zur Reichweite eines Inhalts. Zeigt, wie stark die Zielgruppe reagiert, gemessen an der Zahl der Personen, die den Inhalt gesehen haben.Vollständige Definition ansehen → liest Dateien, führt Tools aus und produziert Output über eine Kommandozeile. Alles, was eine Shell ausführen kann, auch ein CI-Runner, kann ihn ausführen. Genau das gibt Ihnen GitHub Actions: eine ephemere Linux-Maschine, die bei einem Event wie pull_request hochfährt.

Die Architektur ist also einfach. Ein PR wird geöffnet. GitHub startet einen Runner. Der Runner installiert Gemini CLI, übergibt ihm den Diff und einen Prompt, und die CLI ruft die Gemini API auf (Flash oder Pro, je nachdem wie schwer der Job ist) und schreibt ein Review zurück in den PR.

Der offizielle Weg: die GitHub Action

Google liefert eine gepflegte GitHub Action, damit Sie die Installation nicht selbst skripten müssen. Das kanonische Setup liegt im Repository google-github-actions/run-gemini-cli. Es kapselt die CLI, übernimmt die Auth und stellt Prompt und Tools als Workflow-Inputs bereit.

Sie authentifizieren sich auf eine von zwei Weisen:

• Ein Gemini API Key aus Google AI Studio, abgelegt als GitHub Secret. Am schnellsten zum Start.
• Vertex AI mit Workload Identity Federation, wenn Sie auf Google Cloud sind und keylose Auth an einen Service Account gebunden wollen. Das ist der Enterprise-Weg und vermeidet langlebige Secrets vollständig. Zur Plattformseite siehe Vertex AI.

Für ein Team-Repo nehmen Sie besser die zweite Variante. Für ein Wochenendprojekt reicht der APIAPIApplication Programming Interface: eine standardisierte Schnittstelle, über die Anwendungen kommunizieren und Daten austauschen, ohne die interne Funktionsweise der jeweils anderen zu kennen.Vollständige Definition ansehen → Key.

Ein Workflow, der jeden Pull Request reviewt

Hier ist ein vollständiger, lauffähiger Workflow. Er triggert, wenn ein PR geöffnet oder aktualisiert wird, führt Gemini CLI mit einem fokussierten Review-Prompt aus und ist abgesichert über die Permissions- und Concurrency-Einstellungen, die ich gleich danach erkläre.

name: Gemini PR Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: gemini-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Gemini code review
        uses: google-github-actions/run-gemini-cli@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}
          prompt: |
            Review the diff for this pull request. Focus only on:
            correctness bugs, security issues, and missing error handling.
            Skip style nits. For each finding, cite the file and line.
            If you find nothing serious, say so in one sentence.

Das ist alles. Die run-gemini-cli Action macht die Schwerarbeit: sie liest den PR-Kontext, lässt das Modell gegen Ihren Prompt laufen und postet das Ergebnis als Kommentar über das GITHUB_TOKEN.

Ein paar bewusste Entscheidungen in dieser Datei lohnen einen genaueren Blick.

Warum fetch-depth: 0

Standardmäßig macht actions/checkout einen Shallow Clone mit nur dem letzten Commit. Ein Reviewer, der den Diff gegen den Base Branch nicht sehen kann, ist nutzlos. fetch-depth: 0 holt die vollständige History, damit die CLI die tatsächlichen Änderungen berechnen und durchdenken kann.

Der Prompt ist eine Spec, kein Wunsch

Beachten Sie: der Prompt benennt genau drei Kategorien und sagt dem Modell ausdrücklich, Style-Kleinkram zu überspringen. Das ist der größte einzelne Hebel für die Review-Qualität. Ein vager Prompt („review this PR“) produziert lautes Rauschen mit wenig Vertrauen, das Ihr Team innerhalb einer Woche stummschaltet. Ein eingegrenzter Prompt produziert Signal.

Behandeln Sie den Prompt wie eine Code-Review-Checkliste, die Sie einem neuen Mitarbeiter geben würden. Benennen Sie, was zählt, benennen Sie, was zu ignorieren ist, und verlangen Sie Quellenangaben, damit ein Mensch jede Behauptung prüfen kann.

GuardrailsGuardrailsRegeln und Kontrollen, die ein KI-System in sicheren, rechtskonformen und markengerechten Grenzen halten und unerwünschte Ausgaben blockieren.Vollständige Definition ansehen →: der Teil, den Leute überspringen

Ein Modell, das PRs kommentieren kann, ist weitgehend harmlos. Ein Modell, das beliebige Tools ausführen, Commits pushen oder Ihre Secrets lesen kann, ist es nicht. CI ist genau der Ort, an dem ein schlampiges Setup zum Incident wird. Hier sind die Guardrails, die zählen, in der Reihenfolge ihrer Priorität.

1. Least-Privilege-Permissions

Der permissions-Block im Workflow ist Ihre erste Mauer. Das Standard-GITHUB_TOKEN ist in vielen Organisationen weitaus mächtiger, als ein Reviewer es braucht.

permissions:
  contents: read
  pull-requests: write

contents: read erlaubt der Action, den Code zu lesen. pull-requests: write erlaubt ihr zu kommentieren. Nichts weiter. Der Job kann nicht auf Branches pushen, keine Workflows bearbeiten, keine Releases anfassen. Wenn eine Prompt Injection in einem böswilligen PR den Agenten zu mehr bringen wollte: das Token hat den Scope einfach nicht.

2. Das Fork-Problem

Das ist die Stelle, an der es Teams erwischt. Das pull_request-Event aus einem geforkten Repository läuft per Design mit einem Read-only-TokenTokenEin Token ist die grundlegende Texteinheit, die Sprachmodelle verarbeiten, oft ein Wortfragment, ein ganzes Wort oder ein Satzzeichen und nicht ein einzelnes Zeichen.Vollständige Definition ansehen → und ohne Zugriff auf Secrets, damit ein Angreifer keinen PR öffnen kann, der Ihren GEMINI_API_KEY exfiltriert.

Es gibt eine verlockende Alternative, pull_request_target, die im Kontext des Base-Repos läuft und sehr wohl Secrets hat. Greifen Sie nicht leichtfertig danach, um Reviews auf Forks zu „reparieren“. Nicht vertrauenswürdigen PR-Code mit Zugriff auf Ihre Secrets auszuführen, ist der klassische GitHub-Actions-Fußschuss. Wenn Sie Forks unterstützen müssen, sichern Sie den Job hinter einem manuellen labeled-Trigger, damit ein Maintainer den Diff prüft, bevor irgendein privilegierter Lauf startet.

3. Modell festlegen und Kosten begrenzen

Wählen Sie Ihre Modellstufe bewusst. Für die meiste PR-Review-Arbeit ist Gemini Flash die richtige Wahl: schnell, günstig und mehr als fähig, Korrektheits- und Security-Probleme in einem Diff zu finden. Reservieren Sie Gemini Pro für Jobs, die tiefes Reasoning über mehrere Dateien brauchen, etwa das Architektur-Review eines großen Feature Branch.

Kombinieren Sie das mit timeout-minutes am Job und **cancel-in-progress-Concurrency (damit ein Force-Push nicht drei Reviews auf einem PR stapelt), und Ihre Ausgaben bleiben vorhersehbar**.

4. Das Modell berät, es entscheidet nicht

Lassen Sie das Review einen Kommentar sein, keinen erforderlichen Status-Check, der Merges blockiert, zumindest am Anfang. Ein LLMLLMEin Large Language Model ist ein KI-System, das auf riesigen Textmengen trainiert wurde, um Sprache vorherzusagen und zu erzeugen. Damit sind Aufgaben wie Schreiben, Zusammenfassen und Beantworten von Fragen möglich.Vollständige Definition ansehen →-Reviewer ist ein zusätzliches Paar Augen, kein Gate. Wenn Sie ihn später zu einem blockierenden Check befördern, halten Sie diesen Check eng gefasst (zum Beispiel nur fehlschlagen bei Findings, die das Modell als sicherheitskritisch einstuft) und behalten Sie einen menschlichen Override-Pfad.

Über Reviews hinaus: Triage, Labels und Slash Commands

PR-Review ist der naheliegende erste Job, aber dieselbe Action kann mehr.

Issue-Triage nach Zeitplan

Richten Sie einen geplanten Workflow auf Ihre offenen Issues und lassen Sie die CLI sie labeln und priorisieren. Der Prompt übernimmt die Klassifizierung, und die issues: write-Permission erlaubt das Setzen von Labels. Das ist in einem lebhaften Repo, in dem sich untriagierte Issues über Nacht stapeln, wirklich nützlich.

Hilfe auf Abruf per Mention

Sie können die Action bei issue_comment triggern und sie antworten lassen, wenn jemand @gemini-cli gefolgt von einer Frage schreibt. Ein Contributor fragt in einem Kommentar „warum schlägt dieser Test unter Windows fehl?“, der Workflow feuert, und Gemini antwortet inline mit Kontext aus dem Repo.

Das Muster ist jedes Mal dasselbe: ein Event triggert den Runner, ein eingegrenzter Prompt plus die richtigen permissions definieren, was der Agent darf, und der Output geht zurück an GitHub. Sobald Sie diesen Loop verinnerlicht haben, bauen Sie jedes davon an einem Nachmittag.

Eigene Instruktionen mit GEMINI.md

Ein repo-weiter Prompt ist gut. Ein repo-weiter Prompt, der Ihre Konventionen kennt, ist besser. Gemini CLI liest eine GEMINI.md-Datei aus Ihrem Repository als dauerhaften Kontext, genauso wie beim lokalen Lauf. Legen Sie eine ins Root, und der CI-Reviewer erbt Ihre Hausregeln, ohne dass Sie sie ins Workflow-YAML stopfen müssen.

# 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.

Jetzt kann Ihr Review-Prompt kurz und generisch bleiben, weil das projektspezifische Wissen in der Versionskontrolle direkt neben dem Code liegt, den es regelt. Wenn sich Konventionen ändern, bearbeiten Sie GEMINI.md in einem normalen PR, und der Reviewer, der diesen PR reviewt, folgt schon den neuen Regeln.

Diese Trennung ist wichtig: der Workflow definiert *Capability* (was der Agent tun darf), und GEMINI.md definiert *Policy* (wie gut in dieser Codebase aussieht). Halten Sie beides auseinander.

Erst lokal, dann CI

Eine Arbeitsgewohnheit erspart Ihnen viele fehlgeschlagene Actions-Läufe: entwickeln Sie den Prompt lokal, bevor Sie ihn committen. Lassen Sie Gemini CLI zuerst auf Ihrer eigenen Maschine gegen einen echten Branch laufen.

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."

Feilen Sie am Wortlaut, bis der Output wirklich brauchbar ist. Erst dann kopieren Sie diesen Prompt in den Workflow. CI ist ein langsamer, unbequemer Ort, um Prompt-Formulierungen zu debuggen, weil jede Änderung ein Commit und ein mehrminütiger Lauf ist. Ihr Laptop ist sofort da.

Key Takeaways

• Nutzen Sie die offizielle Action. Bauen Sie google-github-actions/run-gemini-cli in einen pull_request-Workflow ein, anstatt die CLI-Installation selbst zu skripten, und bevorzugen Sie für Team-Repos Vertex AI mit Workload Identity Federation gegenüber einem langlebigen API Key.
• Grenzen Sie den Prompt wie eine Checkliste ein. Benennen Sie die paar Dinge, die der Reviewer finden soll, und sagen Sie ihm ausdrücklich, den Rest zu überspringen. Ein fokussierter Prompt ist der Unterschied zwischen einem vertrauenswürdigen Reviewer und Rauschen, das Ihr Team stummschaltet.
• Sichern Sie die Permissions ab. Vergeben Sie nur contents: read und pull-requests: write, greifen Sie nie zu pull_request_target, um Forks ohne Maintainer-Gate zu unterstützen, und lassen Sie das Review ein Kommentar sein, kein Merge-blockierendes Gate, bis Sie ihm vertrauen.
• Wählen Sie die Stufe bewusst. Standardmäßig Gemini Flash für Diff-Review und Kostenkontrolle; auf Pro nur für tiefes Reasoning über mehrere Dateien hochstufen.
• Legen Sie Policy in `GEMINI.md`. Halten Sie Projektkonventionen in einer versionierten Datei, damit der Workflow generisch bleibt und Ihre Regeln neben dem Code leben, und testen Sie Prompts immer lokal, bevor Sie sie in CI committen.