Gemini CLI auf GitHub und in der CI

# Gemini CLI auf GitHub und in der CI

Sie kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen Gemini jeden Pull Request lesen lassen, den Ihr Team öffnet, ein strukturiertes Review hinterlassen lassen und dabei nie einen Browser-Tab öffnen. Das ist das Versprechen der Gemini CLI in GitHub Actions: 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 aufzusetzen. Keine Demo, die „sieht gut aus“ postet, sondern ein Reviewer, der in der 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 als IDE-Begleiter, der Code vervollständigt und Fragen im 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. ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → liest Dateien, führt Tools aus und produziert Output von einer Kommandozeile aus. 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 die Gemini CLI, übergibt ihr den Diff und einen Prompt, und die CLI ruft die Gemini APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → auf (Flash oder Pro, je nach Umfang der Aufgabe) 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 Arten:

• Mit einem Gemini API Key aus Google AI Studio, gespeichert als GitHub Secret. Am schnellsten zum Start.
• Mit Vertex AI und 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 die zweite Variante. Für ein Wochenendprojekt reicht der APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → Key.

Ein Workflow, der jeden Pull Request reviewt

Hier ein vollständiger, lauffähiger Workflow. ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → wird ausgelöst, wenn ein PR geöffnet oder aktualisiert wird, führt die Gemini CLI mit einem fokussierten Review-Prompt aus und ist mit den Permissions- und Concurrency-Einstellungen abgesichert, 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 Action run-gemini-cli 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.

Bei einigen bewussten Entscheidungen in dieser Datei lohnt es sich, kurz innezuhalten.

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 darüber nachdenken kann.

Der Prompt ist eine Spezifikation, kein Wunsch

Beachten Sie: Der Prompt nennt genau drei Kategorien und sagt dem Modell ausdrücklich, Style-Kleinkram zu überspringen. Das ist der größte Einzelhebel für Review-Qualität. Ein vager Prompt („review this PR“) produziert lautes Rauschen mit geringem Vertrauen, das Ihr Team binnen einer Woche stummschaltet. Ein eng gefasster Prompt produziert Signal.

Behandeln Sie den Prompt wie eine Code-Review-Checkliste, die Sie einem neuen Mitarbeiter in die Hand drücken würden. Benennen Sie, was zählt, benennen Sie, was ignoriert werden soll, und fordern Sie Quellenangaben, damit ein Mensch jede Behauptung prüfen kann.

Guardrails: der Teil, den man überspringt

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. Die CI ist genau der Ort, an dem ein schlampiges Setup zum Incident wird. Hier die Guardrails, die zählen, nach Priorität.

1. Least-Privilege-Permissions

Der permissions-Block im Workflow ist Ihre erste Mauer. Das Standard-GITHUB_TOKEN ist in vielen Organisationen deutlich 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 in Branches pushen, keine Workflows bearbeiten, keine Releases anfassen. Wenn eine Prompt Injection in einem bösartigen PR den Agenten zu mehr bringen wollte: Das 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.Vollständige Definition ansehen → hat den Scope einfach nicht.

2. Das Fork-Problem

Das ist die Sache, die Teams erwischt. Das pull_request-Event aus einem geforkten Repository läuft bewusst mit einem 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.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 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-Selbstschuss. Wenn Sie Forks unterstützen müssen, hängen Sie den Job hinter einen manuellen labeled-Trigger, damit ein Maintainer den Diff prüft, bevor irgendein privilegierter Lauf startet.

3. Modell festlegen und Kosten deckeln

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

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

4. Das Modell berät, es entscheidet nicht

Behalten Sie das Review als Kommentar, nicht als Required Status Check, der Merges blockiert, jedenfalls zu Beginn. Ein 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.Vollständige Definition ansehen →-Reviewer ist ein zusätzliches Paar Augen, kein Gate. Wenn Sie ihn später zu einem blockierenden Check befördern, fassen Sie diesen Check eng (zum Beispiel nur Fehlschlag bei Findings, die das Modell als sicherheitskritisch einstuft) und behalten Sie einen Override-Pfad für Menschen.

Über das Review hinaus: Triage, Labels und Slash-Commands

PR-Review ist die naheliegende erste Aufgabe, 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 macht die Klassifikation, und die Permission issues: write erlaubt ihr, Labels zu setzen. Das ist in einem geschäftigen Repo, in dem sich über Nacht untriagierte Issues stapeln, wirklich nützlich.

Hilfe auf Abruf per Mention

Sie kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen die Action bei issue_comment auslösen und sie antworten lassen, wenn jemand @gemini-cli gefolgt von einer Frage schreibt. Ein Contributor fragt im 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 startet den Runner, ein eng gefasster Prompt plus die richtigen permissions definieren, was der Agent darf, und der Output geht zurück an GitHub. Wenn Sie diese Schleife verinnerlicht haben, bauen Sie jede dieser Varianten an einem Nachmittag.

Eigene Instruktionen mit GEMINI.md

Ein repo-weiter Prompt ist gut. Ein repo-weiter Prompt, der Ihre Konventionen kennt, ist besser. Die Gemini CLI liest eine GEMINI.md-Datei aus Ihrem Repository als dauerhaften Kontext, genauso wie lokal. Legen Sie eine im Root ab, und der CI-Reviewer erbt Ihre Hausregeln, ohne dass Sie sie in das Workflow-YAML stopfen.

# 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, für den es gilt. 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 getrennt.

Erst lokal, dann CI

Eine Arbeitsgewohnheit erspart Ihnen viele fehlgeschlagene Actions-Läufe: Entwickeln Sie den Prompt lokal, bevor Sie ihn committen. Lassen Sie die 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 an der Formulierung, bis der Output wirklich nützlich ist. Erst dann fügen Sie diesen Prompt in den Workflow ein. Die 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.

Die wichtigsten Punkte

• Nutzen Sie die offizielle Action. Bauen Sie google-github-actions/run-gemini-cli in einen pull_request-Workflow ein, statt die CLI-Installation selbst zu skripten, und ziehen Sie für Team-Repos Vertex AI mit Workload Identity Federation einem langlebigen APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → Key vor.
• Fassen Sie den Prompt wie eine Checkliste. Benennen Sie die wenigen 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.
• Schränken Sie Permissions ein. Vergeben Sie nur contents: read und pull-requests: write, greifen Sie nie ohne Maintainer-Gate zu pull_request_target, um Forks zu unterstützen, und lassen Sie das Review ein Kommentar sein, kein Merge-Blocker, bis Sie ihm vertrauen.
• Wählen Sie die Stufe bewusst. Standard ist Gemini Flash für Diff-Reviews und Kostenkontrolle; auf Pro gehen Sie nur für tiefes Reasoning über mehrere Dateien.
• Policy gehört in `GEMINI.md`. Halten Sie Projektkonventionen in einer versionierten Datei, damit der Workflow generisch bleibt und Ihre Regeln neben dem Code liegen, und testen Sie Prompts immer lokal, bevor Sie sie in die CI committen.