GitHub-Actions-Pinning und Sicherheit

Wie Sie als Paketentwickler zum Schutz vor Supply-Chain-Angriffen GitHub-Actions-Abhängigkeiten von Versionen auf SHA-Hashes pinnen — inklusive Auto-Update-Strategie mit Dependabot.

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

Vorteil	Beschreibung
Schutz vor Supply-Chain-Angriffen	Da ein konkreter Commit-Hash referenziert wird, sind Sie gegen Manipulationen geschützt.
Auditierbarkeit	Sie können nachvollziehen, wann welche Action auf welche Version aktualisiert wurde.
Explizites Update	Dependabot schlägt vor — jedes Update durchläuft ein menschliches Review.
Reproduzierbarkeit	Bei identischem Commit-Hash erhalten Sie exakt dieselbe Umgebung.

​

Nachteile

Nachteil	Gegenmaßnahme
Aufwand bei der Ersteinrichtung	Mit pinact automatisieren
Höherer Update-Aufwand	Dependabot erzeugt automatische PRs — Aufwand minimal
Schlechtere Lesbarkeit	Kommentar mit Versionsangabe erhält die Lesbarkeit

​

Checkliste für Sicherheitsprüfungen

Checkliste bei neuen Paketprojekten.

Ersteinrichtung

• .github/dependabot.yml anlegen
• Alle bestehenden Actions auf SHA pinnen
• pinact oder manuelle Prüfung abgeschlossen
• Erfolgreicher Workflow-Lauf verifiziert

Regelmäßige Wartung

• 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

Audit

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