Zum Hauptinhalt springen
Um dem Risiko von Angriffen und Manipulationen an GitHub Actions entgegenzuwirken, setzen auch die offiziellen Laravel-Projekte auf das Pinning von GitHub Actions. Diese Seite erläutert praxisnah die Sicherheitsmaßnahmen, die Paketentwickler umsetzen sollten.
Diese Seite ist eine Schwesterseite von Grundlagen der Paketentwicklung und setzt Grundkenntnisse zu GitHub Actions voraus.

Sicherheitsrisiken bei GitHub Actions

Gefahren einer Tag-basierten Referenz

Üblicherweise werden GitHub Actions per Tag referenziert:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
Die Probleme dieses Vorgehens:
  • Tags sind verschiebbar — sie können gelöscht und mit demselben Namen neu erstellt werden.
  • Manipulationsrisiko — bei Übernahme des Repo-Accounts kann bösartiger Code eingeschleust werden.
  • Supply-Chain-Angriff — wenn eine abhängige Action kompromittiert wird, wird auch Ihr Workflow kompromittiert.

Umgang in offiziellen Laravel-Projekten

Sowohl laravel/laravel als auch laravel/framework pinnen alle Actions auf Commit-Hashes (SHA).
# Sichere Referenzierung
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

Strategie für die Umsetzung

Schritt 1: Dependabot-Konfiguration anlegen

Legen Sie in Ihrem Paket-Repository die Datei .github/dependabot.yml an. Sie können die Datei von Laravel direkt übernehmen.
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 5
    groups:
      github-actions:
        patterns:
          - "*"
Diese Datei übernimmt folgende Aufgaben:
  • Automatisches Scannen — sucht nach neuen Versionen der GitHub Actions.
  • Automatische PRs — erstellt bei Updates automatisch Update-PRs.
  • Update-Steuerung — nicht gepinnte Actions werden per Version aktualisiert, gepinnte Actions per SHA.

Schritt 2: Bestehende Actions auf SHAs pinnen

Ersetzen Sie in Ihren Workflows alle Action-Referenzen durch SHA-Hashes. Werkzeuge wie pinact automatisieren das.

Automatisierung mit pinact

# Actions in Workflows auf SHAs pinnen
pinact run

Manuell umstellen

Ohne pinact ermitteln Sie die Commit-SHA jeder Action über die GitHub-Seite Lookup latest version und ersetzen manuell.
# Vorher
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
  with:
    php-version: ${{ matrix.php }}

# Nachher
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
- uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
  with:
    php-version: ${{ matrix.php }}

Schritt 3: Dependabot aktivieren

Committen und pushen Sie .github/dependabot.yml — Dependabot beginnt dann automatisch zu scannen.

Wie Dependabot automatisch aktualisiert

Dependabot wendet je nach Zustand der Datei unterschiedliche Update-Strategien an.

Nicht gepinnte Actions

# Vor dem Pinning
- uses: actions/checkout@v4
Dependabot-Update: Aktualisiert den Versionsbereich auf eine neue Version.
# Von Dependabot erzeugter PR
- uses: actions/checkout@v5
Bequem, verträgt sich mit verschobenen Tags — aber Sicherheitsrisiken bleiben.

Gepinnte Actions

# Nach dem Pinning
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
Dependabot-Update: Aktualisiert auf den Commit-Hash der neuen Version.
# Von Dependabot erzeugter PR
- uses: actions/checkout@f1d3225b54b677ba3e72df8c464cb6cf6dc1aebf  # v4
Die sicherste Variante. Auch neue Versionen werden über Commit-Hashes referenziert und sind manipulationsresistent.

Beispielhafte Workflow-Umsetzung

Ein vollständiges Beispiel mit mehreren Workflows.
name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      fail-fast: false
      matrix:
        php: [8.2, 8.3, 8.4]
        laravel: ["^12.0", "^13.0"]

    steps:
      - uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
        with:
          fetch-depth: 0

      - name: Setup PHP
        uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip, intl, sqlite3
          coverage: none

      - name: Install dependencies
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" \
                           --no-interaction --no-update
          composer update --prefer-dist --no-interaction

      - name: Run tests
        run: vendor/bin/pest

  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

      - name: Setup PHP
        uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
        with:
          php-version: "8.4"
          extensions: dom, curl, libxml, mbstring, zip
          coverage: none

      - name: Install dependencies
        run: composer install --prefer-dist --no-interaction

      - name: Run static analysis
        run: vendor/bin/phpstan

Umgang mit Dependabot-Update-PRs

Update-PRs von Dependabot bearbeiten Sie wie folgt.

PR für ein einzelnes Action-Update

Bump shivammathur/setup-php from v1 to v2
Für einfache Updates gehen Sie so vor:
  1. Ergebnisse der Workflow-Läufe prüfen.
  2. Auf Breaking Changes prüfen.
  3. Mergen — fertig.

Sicherheitsupdate-PR

[SECURITY] Bump actions/checkout to a5ac7e51b41094c7fcab2042361574b0021804ab
Sicherheitsbezogene Updates werden priorisiert gemergt.

Gruppen-Updates mehrerer Actions

Wenn Sie in dependabot.yml groups konfigurieren, kommen mehrere Actions in einem einzigen PR.
groups:
  github-actions:
    patterns:
      - "*"
Das reduziert die Anzahl der Merge-Vorgänge.

Vor- und Nachteile des Pinnings

Vorteile

VorteilBeschreibung
Schutz vor Supply-Chain-AngriffenDa ein konkreter Commit-Hash referenziert wird, sind Sie gegen Manipulationen geschützt.
AuditierbarkeitSie können nachvollziehen, wann welche Action auf welche Version aktualisiert wurde.
Explizites UpdateDependabot schlägt vor — jedes Update durchläuft ein menschliches Review.
ReproduzierbarkeitBei identischem Commit-Hash erhalten Sie exakt dieselbe Umgebung.

Nachteile

NachteilGegenmaßnahme
Aufwand bei der ErsteinrichtungMit pinact automatisieren
Höherer Update-AufwandDependabot erzeugt automatische PRs — Aufwand minimal
Schlechtere LesbarkeitKommentar mit Versionsangabe erhält die Lesbarkeit

Checkliste für Sicherheitsprüfungen

Checkliste bei neuen Paketprojekten.
  • .github/dependabot.yml anlegen
  • Alle bestehenden Actions auf SHA pinnen
  • pinact oder manuelle Prüfung abgeschlossen
  • Erfolgreicher Workflow-Lauf verifiziert
  • Dependabot-Update-PRs mindestens einmal pro Woche reviewen
  • Sicherheitsupdates priorisiert mergen
  • Neue Actions grundsätzlich per SHA referenzieren
  • Einmal pro Monat den Zustand aller Workflows prüfen
  • Alle Action-Referenzen sind SHAs
  • Dependabot ist aktiv
  • Alle Dependabot-PRs der letzten 6 Monate sind gemergt

Verwandte Seiten

Grundlagen der Paketentwicklung

Wie Sie Laravel-Pakete rund um Service Provider entwickeln.

Versionskompatibilität von Paketen verwalten

Strategien für Paket-Anpassungen bei Major-Upgrades von Laravel.
Zuletzt geändert am 13. Juli 2026