Fortgeschrittene GitHub Actions mit Claude Code: Permissions, OIDC, cache und matrix CI

GitHub Actions ist einfach, solange nur Tests nach einem push laufen sollen. Schwieriger wird es, wenn Permissions eng sein müssen, cache zuverlässig bleiben soll, mehrere Umgebungen geprüft werden, cloud deploy ohne langlebige Schlüssel laufen soll und Claude Code keine Secrets sehen darf.

Dieser Leitfaden nutzt Claude Code als Partner für Workflow-Design, nicht als YAML-Automat. Die Beispiele sind vollständige GitHub Actions Workflows, die du kopieren und anpassen kannst. Entscheidend ist, dass jeder job erklären kann, warum er welche Permission braucht, welche Secrets sichtbar sind und was bei Pull Requests aus Forks passiert.

Ich habe die Empfehlungen mit den offiziellen GitHub Docs für workflow syntax, GITHUB_TOKEN permissions, AWS OIDC, dependency caching, concurrency und Claude Code GitHub Actions abgeglichen.

Architektur

Ein fortgeschrittener Workflow automatisiert nicht blind mehr. Er begrenzt den Schaden, liefert nachvollziehbare Fehler, beendet veraltete runs und behält menschliche Freigaben für production changes.

flowchart LR
  PR["Pull request"] --> Gate["matrix test and lint"]
  Gate --> Cache["lockfile cache"]
  Gate --> Claude["Claude Code review"]
  Gate --> Deploy["OIDC deploy"]
  Deploy --> Env["GitHub environment approval"]
  Env --> AWS["AWS role"]

Ein paar Begriffe vorab: Matrix ist eine Kombinationstabelle, zum Beispiel Node.js 22 und 24 auf Ubuntu und Windows. OIDC bedeutet OpenID Connect und tauscht eine kurzlebige GitHub Actions Identität gegen cloud credentials aus. Dadurch müssen keine langlebigen AWS access keys in GitHub Secrets liegen. Concurrency steuert gleichzeitige Ausführungen. Permissions legen fest, was der GITHUB_TOKEN darf.

Anwendungsfälle

Der erste Anwendungsfall ist ein Pull-Request-Qualitätsgate. Lint, type-check und tests laufen vor dem Merge auf mehreren Umgebungen. So findest du Windows-Pfadprobleme, Unterschiede zwischen Node.js-Versionen und lockfile drift früher.

Der zweite Anwendungsfall ist staging deploy. Wenn main grün ist, übernimmt GitHub Actions per OIDC eine AWS IAM role und deployed ohne statischen Schlüssel. Für production sollte ein GitHub Environment mit required reviewers dazukommen.

Der dritte Anwendungsfall ist gemeinsames CI in einem monorepo. Wenn mehrere packages denselben Node setup, install und test wiederholen, verhindert ein reusable workflow Versionsdrift.

Der vierte Anwendungsfall ist Pull-Request-Review mit Claude Code. Starte mit Analyse und Kommentaren. Schreibrechte sollten erst folgen, wenn branch protection, required review und rollback klar sind.

Prompt für Claude Code

Fordere zuerst ein Design unter Einschränkungen an.

Design GitHub Actions for this repository.
The goals are pull request quality gates, staging deployment, and Claude Code review.

Constraints:
- Use least-privilege GITHUB_TOKEN permissions.
- Use OIDC for AWS. Do not store long-lived AWS access keys in Secrets.
- Include package-lock.json in dependency cache keys.
- Assume secrets are not available on forked pull requests.
- If pull_request_target is suggested, explain why PR head code is not checked out.
- Produce GitHub Actions YAML that is valid as written.

End with concrete failure cases and verification steps.

Damit muss Claude Code Sicherheitsentscheidungen begründen, statt nur eine Standardvorlage auszugeben.

PR-Qualitätsgate

Dieser Workflow nutzt actions/checkout@v6 und actions/setup-node@v6, aktuelle major-Versionen im Juni 2026. GitHub-hosted runners funktionieren normalerweise direkt. Bei self-hosted runners prüfst du zuerst die runner-Version.

name: pr-quality-gate

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: pr-quality-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    name: node-${{ matrix.node }}-${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [22, 24]

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ matrix.node }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type check
        run: npm run typecheck

      - name: Test
        run: npm test

Der job braucht nur contents: read, weil Tests nicht ins Repository schreiben. concurrency beendet alte runs auf demselben branch. Der cache hängt an package-lock.json; ein kompletter node_modules cache ist oft fragiler, weil native modules und OS-Unterschiede hineinspielen.

AWS Deploy mit OIDC

Das sichere Muster: GitHub als OIDC provider in AWS registrieren, eine enge IAM role anlegen und die trust policy nach repository, branch oder environment einschränken. Im workflow ist id-token: write nötig, damit GitHub den OIDC token ausstellen kann.

name: deploy-staging

on:
  workflow_dispatch:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

concurrency:
  group: deploy-staging
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    environment: staging

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: arn:aws:iam::123456789012:role/claude-code-github-actions-staging
          aws-region: ap-northeast-1

      - name: Verify caller identity
        run: aws sts get-caller-identity

      - name: Deploy
        run: |
          npm ci
          npm run build
          echo "Deploy command goes here"

Ersetze role ARN, Region und deploy command. Für production nutzt du ein eigenes environment und required reviewers.

Reusable workflow

Ein reusable workflow lohnt sich, wenn mehrere workflows dieselbe Prüfung wiederholen. So bleibt auch die action-Version an einer Stelle.

# .github/workflows/reusable-node-check.yml
name: reusable-node-check

on:
  workflow_call:
    inputs:
      node-version:
        required: false
        type: string
        default: "24"

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node
        uses: actions/setup-node@v6
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Install
        run: npm ci

      - name: Check
        run: |
          npm run lint
          npm run typecheck
          npm test

Aufrufender Workflow:

# .github/workflows/ci.yml
name: ci

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  node-check:
    uses: ./.github/workflows/reusable-node-check.yml
    with:
      node-version: "24"

Verstecke echte Unterschiede nicht in einem riesigen reusable workflow. Wenn packages unterschiedliche Befehle brauchen, lass Claude Code gemeinsamen setup und package-spezifische Schritte trennen.

PR Review mit Claude Code

Claude Code Action v1 nutzt anthropics/claude-code-action@v1, prompt und claude_args. Alte @beta- oder direct_prompt-Beispiele solltest du nicht übernehmen.

name: claude-pr-review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Claude Code review
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request as a senior engineer.
            Focus on security, broken tests, unnecessary permissions, and missing verification.
            Do not modify files. Leave concise review comments only.
          claude_args: |
            --max-turns 5

Der if überspringt Forks, weil Repository-Secrets dort normalerweise nicht verfügbar sind. Für Forks brauchst du einen separaten Low-Trust-Pfad ohne Secrets und ohne Ausführung fremden Codes mit hohen Rechten.

Häufige Fehler

Der gefährlichste Fehler ist pull_request_target mit checkout des PR-heads. Dieses Event kann näher an den Rechten des base repository laufen; Code aus einem externen Fork damit auszuführen, ist riskant.

Ein weiterer Fehler ist das Ausgeben von Secrets beim Debugging. GitHub maskiert viele exakte Werte, aber abgeleitete Strings, JSON, base64 und externe debug logs können trotzdem leaken. Gib Claude Code Secret-Namen und Zweck, nicht die Werte.

Cache kann ebenfalls Probleme erzeugen. Eine zu breite key wie node-cache kann nach lockfile-Änderungen alte dependencies zurückholen. Nutze cache-dependency-path oder hashFiles('**/package-lock.json').

Matrix kann explodieren. Zwei OS mal zwei Node-Versionen sind sinnvoll; drei OS, vier runtimes und acht packages ergeben 96 jobs. PRs brauchen die kleine Matrix, nightly runs können breiter sein.

Behalte außerdem action major-Versionen im Blick. 2026 nutzen viele offizielle actions neuere Node runtimes. Bei self-hosted runners kommt das runner-Update vor dem workflow-Update.

Monetarisierung

Sicheres CI schützt Umsatzarbeit: Landingpages, bezahlte Templates, Checkout-Flows, Lead-Formulare und Kursinhalte lassen sich in kleinen PRs ausliefern, ohne deploy-Brüche oder Secret-Leaks zu riskieren. Allein startest du mit dem kostenlosen Claude Code Cheat Sheet. Teams, die permissions, OIDC, Claude Code review, branch protection und monorepo CI auf ein echtes Repository anpassen möchten, können Claude Code Training und Beratung nutzen.

Passende Artikel: CI/CD setup, Git workflow, testing strategy und security best practices.

Geprüftes Ergebnis

Für diesen Artikel habe ich die YAML-Blöcke aus dem MDX extrahiert und mit einem YAML parser geprüft. Die Beispiele werden als YAML gelesen und decken on, permissions, concurrency, matrix, reusable workflow, OIDC deploy und Claude Code Action v1 ab. Vor dem Einsatz musst du AWS role ARN, npm scripts, environment und ANTHROPIC_API_KEY an dein Repository anpassen.