Claude Code GitHub Actions: Einrichtung und Workflows

Mit Claude Code GitHub Actions führst du Claude Code in einem GitHub-Workflow aus. Du erwähnst @claude in einem Issue oder Pull Request, und Claude liest den Code, antwortet, schreibt einen Fix auf einem neuen Branch oder prüft den Diff, alles auf einem GitHub-Runner. Am schnellsten richtest du es ein, indem du Claude Code in deinem Repository öffnest und /install-github-app ausführst. Der Befehl installiert die Claude GitHub App, speichert deinen Key als Repository-Secret und öffnet einen Pull Request mit den Workflow-Dateien.

Diese Anleitung deckt beide Einrichtungswege ab, die Inputs der offiziellen anthropics/claude-code-action, die zwei Modi (Erwähnungen und Automatisierung), einen fertigen PR-Review-Workflow, Secrets, Kosten- und Berechtigungskontrollen und die Fälle, in denen Claude lokal die bessere Wahl ist. Alles hier folgt der Dokumentation von Anthropic und dem README der Action mit Stand Oktober 2026. Wenn du einen Agenten suchst, der rote CI-Builds selbst repariert, gibt es dafür einen eigenen Beitrag: CI-Fehler mit KI automatisch beheben.

Was die Action macht

anthropics/claude-code-action@v1 ist eine GitHub Action, die den Claude-Code-Agenten auf deinem eigenen GitHub-Runner ausführt. Sie arbeitet in zwei Modi:

• Interaktiv (Erwähnungen). Gibst du ihr keinen prompt, wartet sie auf eine Trigger-Phrase, standardmäßig @claude. Die Phrase kann in einem Issue- oder PR-Kommentar stehen, in einem PR-Review oder im Titel oder Text eines neuen Issues. Claude antwortet in einem Kommentar und kann einen Branch mit Änderungen pushen.
• Automatisierung. Setzt du prompt, führt Claude diese Aufgabe aus, sobald der Workflow auslöst, ohne dass jemand es erwähnen muss. Die Ergebnisse landen im Lauf-Log, außer der Prompt oder ein Plugin sagt Claude, dass es irgendwo posten soll. So baust du PR-Reviews, geplante Berichte und Issue-Triage.

Der Agent folgt denselben Regeln wie in deinem Terminal. Er liest CLAUDE.md, nutzt die Tools, die du erlaubst, und hält beim Turn-Limit an, das du festlegst.

Schritt 1: schnelle Einrichtung mit /install-github-app

Öffne Claude Code im Repository und führe aus:

/install-github-app

Bevor du loslegst, prüfe drei Dinge:

• Du bist Admin des Repositorys. Sowohl die Installation der App als auch das Anlegen von Secrets brauchen Admin-Rechte.
• Das Repository liegt auf github.com. Liegt das Remote auf gitlab.com oder bitbucket.org, zeigt der Befehl einen Hinweis und beendet sich.
• Die GitHub CLI ist angemeldet. Führe vorher gh auth login aus, falls noch nicht geschehen.

Der Befehl führt dich durch den Ablauf. Er installiert die Claude GitHub App im Repo und fragt, wie sich Claude authentifizieren soll. Dann speichert er entweder ANTHROPIC_API_KEY (einen API-Key) oder CLAUDE_CODE_OAUTH_TOKEN (ein Token, das an dein Claude-Abo gebunden ist) als Repository-Secret. Gibt es schon einen Key, kann er ihn weiterverwenden. Zum Schluss pusht er einen Branch mit den Workflow-Dateien und öffnet einen Pull Request, den du mergst.

Du bekommst zwei Workflows: claude.yml beantwortet @claude-Erwähnungen, und claude-code-review.yml prüft Pull Requests. Drücke Esc, um mittendrin abzubrechen, oder wähle nach der Installation der App „Skip for now“, wenn du die Workflows selbst schreiben willst. Führst du den Befehl später erneut aus, bietet er an, die Workflow-Datei auf die neueste Version zu aktualisieren.

Die schnelle Einrichtung funktioniert mit der Claude API und mit Claude-Abos. Nutzt du Amazon Bedrock, Google Cloud oder Microsoft Foundry, nimm den manuellen Weg und den Abschnitt zu Cloud-Anbietern in der Dokumentation.

Schritt 2: manuelle Einrichtung

Passt der Befehl nicht zu deiner Situation, sind das dieselben drei Schritte von Hand:

1. Installiere die Claude GitHub App von github.com/apps/claude im Repository. Die Action nutzt deren Berechtigungen Contents, Issues und Pull requests, jeweils mit Lese- und Schreibzugriff.
2. Lege ein Secret an unter Settings → Secrets and variables → Actions:
   • ANTHROPIC_API_KEY: ein API-Key aus der Claude Console, abgerechnet pro Token, oder
   • CLAUDE_CODE_OAUTH_TOKEN: führe lokal claude setup-token aus, um eines zu erstellen; es funktioniert mit den Tarifen Pro, Max, Team und Enterprise.
3. Kopiere den Beispiel-Workflow claude.yml aus dem Ordner examples/ der Action nach .github/workflows/.

Hier ist ein funktionierender Workflow für Erwähnungen:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Zwei Berechtigungen übersieht man leicht. id-token: write ist für die Standard-Authentifizierung über die GitHub App nötig. actions: read lässt Claude CI-Ergebnisse lesen, sodass du fragen kannst, warum ein Check fehlgeschlagen ist. Nutzt du ein Abo-Token, ersetze die letzte Zeile durch claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Für eine Organisation schlägt die Dokumentation vor, die App auf Organisationsebene zu installieren, den Key in ein Actions-Secret der Organisation zu legen und aus jedem Repo einen wiederverwendbaren Workflow aufzurufen. Für gemeinsame Secrets empfiehlt sie außerdem einen API-Key statt eines OAuth-Tokens, weil ein Token zum Abo einer einzelnen Person gehört. Willst du gar keinen langlebigen Key speichern, unterstützt die Action Workload Identity Federation (OIDC) über die Inputs anthropic_federation_rule_id und anthropic_organization_id.

Schritt 3: @claude in Issues und Pull Requests nutzen

Sobald der Workflow auf dem Default-Branch liegt, schreibst du einen Kommentar:

@claude why does the checkout test fail on Node 22? Fix it if the cause is in our code.

@claude implement this issue. Keep the public API unchanged and add tests.

@claude review the error handling in src/payments/ and suggest changes inline.

Claude antwortet in einem Kommentar. Ändert es Code, pusht es auf einen Branch, der mit claude/ beginnt (das ändert der Input branch_prefix), und gibt dir einen Link, um den Pull Request zu öffnen. Ein paar Regeln entscheiden, wer einen Lauf starten darf:

• Wer kommentiert, braucht Schreibzugriff. Nutzer ohne ihn werden ignoriert, außer du trägst sie in allowed_non_write_users ein, was zusätzlich dein eigenes github_token braucht.
• Bots werden ignoriert, außer du nennst sie in allowed_bots. Mit "*" werden alle Bots akzeptiert, wovon das README bei öffentlichen Repositorys abrät.
• Der Trigger ist ein ganzes Wort. @claude funktioniert, /claude und @claude-bot nicht. Mit trigger_phrase änderst du ihn bei Bedarf.

Außerdem gibt es assignee_trigger (startet, wenn ein Issue einem bestimmten Nutzer zugewiesen wird) und label_trigger (startet, wenn ein Label hinzugefügt wird, standardmäßig claude). Kombiniere sie mit den passenden issues-Event-Typen in on:.

Schritt 4: ein automatischer PR-Review-Workflow

Der folgende Review-Workflow ist der, den die Dokumentation mitliefert. Er läuft bei jedem geöffneten, aktualisierten, wieder geöffneten oder zur Prüfung bereiten Pull Request, ohne dass jemand @claude tippt:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Was die einzelnen Teile tun:

• plugin_marketplaces und plugins laden das offizielle code-review-Plugin.
• prompt führt dessen Befehl auf dem aktuellen PR aus. --comment postet die Befunde als Inline-Kommentare oder als einen einzigen zusammenfassenden Kommentar.
• Die Zeile claude_args ist Pflicht. Ohne --allowedTools für das Inline-Kommentar-Tool startet der MCP-Server, der die Kommentare postet, nicht.

Das Plugin überspringt Draft-, geschlossene und triviale PRs sowie PRs, die es schon kommentiert hat. Pull Requests aus Forks eines öffentlichen Repositorys bekommen keine Repository-Secrets, also läuft das Review bei ihnen nicht. Anthropic bietet außerdem ein separates, verwaltetes Produkt namens Code Review an, das PRs ganz ohne Workflow-Datei prüft. Die Action ist die Variante, die du selbst steuerst und auf deinem eigenen Runner ausführst.

Einen breiteren Blick darauf, was KI-Review findet und was nicht, gibt KI-Code-Review.

Schritt 5: geplante und eigene Automatisierungen

Mit prompt kannst du jede Aufgabe bei jedem GitHub-Event ausführen. Eine tägliche Zusammenfassung sieht so aus:

name: Daily report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Summarize yesterday's commits and open issues"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

Denk daran: Mit einem reinen Prompt hat Claude weder eine Shell noch Zugriff auf die GitHub API, bis du Tools mit --allowedTools oder einer permissions.allow-Regel im Input settings freigibst. Geplante Workflows laufen nur vom Default-Branch aus, und GitHub deaktiviert sie in öffentlichen Repositorys nach 60 Tagen ohne Aktivität.

Die Inputs, die du wirklich brauchst

Die Action hat viele Inputs. Das sind die gängigen:

Weitere nützliche aus dem README: base_branch und branch_prefix dafür, wohin Claude pusht, use_sticky_comment für einen einzigen Kommentar, der sich aktualisiert, track_progress, um bei PR- und Issue-Events Tracking-Kommentare zu posten, use_commit_signing zum Signieren von Commits und additional_permissions (zum Beispiel actions: read). Die Action gibt außerdem Outputs wie branch_name, session_id und structured_output für spätere Schritte zurück.

Hast du die Beta genutzt, ist das Upgrade reine Fleißarbeit. Ändere @beta zu @v1, entferne mode, benenne direct_prompt in prompt um, verschiebe max_turns und model nach claude_args und mach aus custom_instructions ein --append-system-prompt.

Secrets: was wohin gehört

• Schreib nie einen Key in eine Workflow-Datei. Nutze ${{ secrets.ANTHROPIC_API_KEY }} oder ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.
• Leg Secrets auf der engsten Ebene ab, die funktioniert: ein Repository-Secret für ein Repo, ein Organisations-Secret, beschränkt auf ausgewählte Repositorys, für viele.
• Lass show_full_output bei öffentlichen Repos aus. Das README warnt, dass die volle Ausgabe in den Logs Secrets offenlegen kann.
• Behandle Issue-Text als nicht vertrauenswürdige Eingabe. Jeder, der ein Issue schreiben kann, kann versuchen, Claude mit darin versteckten Anweisungen zu steuern. Die Regel zum Schreibzugriff ist dein wichtigster Schutz, also lockere allowed_non_write_users oder allowed_bots nicht leichtfertig. Prompt Injection und Sicherheit von KI-Coding-Agenten behandeln die Risiken genauer.

Kosten und Berechtigungen im Griff behalten

Jeder Lauf kostet doppelt: GitHub-Actions-Minuten auf dem Runner und Claude-Tokens (oder Abo-Nutzung, wenn du ein OAuth-Token verwendest). Die Hebel, die die Dokumentation empfiehlt:

• Turns begrenzen: claude_args: "--max-turns 5" verhindert, dass ein Lauf in einer Schleife hängt.
• Ein Job-Timeout setzen mit timeout-minutes am Job.
• Concurrency nutzen, damit eine Reihe schneller Pushes nicht fünf Reviews desselben PRs startet:

concurrency:
  group: claude-${{ github.event.pull_request.number || github.event.issue.number }}
  cancel-in-progress: true

• Die Tools eingrenzen. Gib --allowedTools nur die Befehle, die die Aufgabe braucht, und halte die Job-permissions bei Review-Jobs auf nur Lesen, wie im Workflow oben.
• CLAUDE.md kurz und konkret halten. Claude lädt sie bei jedem Lauf, eine lange Datei kostet also jedes Mal Tokens. CLAUDE.md schreiben hat eine Vorlage.
• Konkrete Anfragen schreiben. „@claude fix the null check in parseDate“ ist günstiger als „@claude look at this“. Issue-Vorlagen helfen den Leuten, bessere zu schreiben.

Häufige Stolperfallen

• Der Workflow liegt nicht auf dem Default-Branch. issue_comment-Workflows laufen nur vom Default-Branch aus, also merge zuerst den Einrichtungs-PR.
• CI läuft nicht bei Claudes Commits. GitHub startet keine Workflows für Commits, die mit dem Standard-GITHUB_TOKEN erstellt wurden. Entferne github_token: ${{ secrets.GITHUB_TOKEN }}, damit die Action die Claude GitHub App nutzt, oder übergib ein Token deiner eigenen App.
• Das Review postet nichts. Prüfe die Zeile --allowedTools "mcp__github_inline_comment__create_inline_comment" und ob der PR ein Draft ist oder aus einem Fork stammt.
• Claude sagt, es könne keine Befehle ausführen. Im Automatisierungsmodus ist standardmäßig nichts erlaubt. Füge die Tools zu --allowedTools hinzu.

Wann du Claude besser lokal ausführst

Die Action ist gut bei Aufgaben, in denen ein fester Auslöser zu einem begrenzten Job führt: eine Frage beantworten, ein kleines Issue umsetzen, einen Diff prüfen, eine tägliche Zusammenfassung schreiben. Schlecht passt sie, wenn:

• Du unterwegs lenken willst. Ein Kommentar-Thread ist langsam, wenn du den Agenten alle paar Minuten korrigieren musst. In einer lokalen Session kannst du unterbrechen, freigeben und umlenken.
• Die Aufgabe deine Umgebung braucht: eine laufende Datenbank, einen lokalen Dienst, Secrets, die nicht in die CI sollen, oder eine GUI, die du dir ansehen musst.
• Du erkundest. Eine lange Untersuchung verbrennt Runner-Minuten und Tokens, ohne dass jemand zusieht. Lokal siehst du, wenn sie abdriftet, und hältst sie an.
• Du mehrere Agenten gleichzeitig willst, jeden in seinem eigenen Worktree, um Ansätze zu vergleichen.

Viele Teams nutzen beides. Die Action übernimmt Routine-Reviews und kleine Issues, und die schwerere Arbeit passiert lokal, wo jemand zusieht.

Die lokale Seite mit AgentVera

AgentVera ist eine Desktop-App, die Claude Code, Codex, opencode und andere Coding-Agent-CLIs nebeneinander in echten Terminals ausführt, mit deinen eigenen Installationen und Logins. Sie deckt die lokale Seite der Aufteilung oben ab:

• Agenten in Panes und Worktrees. Lass mehrere Claude-Code-Agenten nebeneinander laufen, jeden in seinem eigenen Git-Worktree, und sieh Diffs und Commits im Panel Git und GitHub.
• Automatisches Code-Review vor dem Pushen: Wenn ein Agent einen Turn beendet, prüft ein Claude-Modell deiner Wahl, was er geschrieben hat, und listet Befunde mit Schweregrad und file:line auf. Es kann sie an den Agenten zurückschicken. Das ist im Free-Tarif enthalten.
• CI/CD-Center listet Läufe von GitHub Actions, GitLab CI und Jenkins an einem Ort. Die Logs eines fehlgeschlagenen Laufs gehen mit einem Klick an einen neuen Agenten.
• Automatisierungen (Pro und Team) können einen Agenten starten, wenn die CI rot wird oder ein Repo-Mitglied einen offenen PR kommentiert. Der Agent arbeitet in seinem eigenen Worktree, und AgentVera pusht nie direkt auf den Default-Branch.

Weil AgentVera jede Agent-CLI ausführt, funktioniert dasselbe Setup auch für andere Agenten. opencode verwenden zeigt diese Seite mit einem anbieterunabhängigen Agenten. Lade AgentVera herunter und probiere es aus.

Fazit

Um Claude Code in GitHub Actions zu bringen, führst du /install-github-app aus, mergst den PR, den der Befehl öffnet, und schreibst @claude in ein Issue. Für automatische Reviews fügst du den Workflow mit dem code-review-Plugin und seiner --allowedTools-Zeile hinzu. Danach hältst du alles begrenzt: mit --max-turns, Job-Timeouts, concurrency, Berechtigungen nur zum Lesen, wo es geht, und Secrets, die nie in der Workflow-Datei landen. Die lange, explorative und umgebungsabhängige Arbeit überlässt du einer lokalen Session, bei der du zusehen kannst.