> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  Diese Seite ist eine Schwesterseite von [Grundlagen der Paketentwicklung](/de/advanced/package-development) und setzt Grundkenntnisse zu GitHub Actions voraus.
</Info>

## Sicherheitsrisiken bei GitHub Actions

### Gefahren einer Tag-basierten Referenz

Üblicherweise werden GitHub Actions per Tag referenziert:

```yaml theme={null}
- 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](https://github.com/laravel/laravel) als auch [laravel/framework](https://github.com/laravel/framework) pinnen alle Actions auf Commit-Hashes (SHA).

```yaml theme={null}
# 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.

```yaml theme={null}
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](https://github.com/suzuki-shunsuke/pinact) automatisieren das.

#### Automatisierung mit pinact

```shell theme={null}
# 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](https://github.com/actions/checkout) und ersetzen manuell.

```yaml theme={null}
# 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

```yaml theme={null}
# Vor dem Pinning
- uses: actions/checkout@v4
```

Dependabot-Update: **Aktualisiert den Versionsbereich auf eine neue Version.**

```yaml theme={null}
# Von Dependabot erzeugter PR
- uses: actions/checkout@v5
```

Bequem, verträgt sich mit verschobenen Tags — aber Sicherheitsrisiken bleiben.

### Gepinnte Actions

```yaml theme={null}
# Nach dem Pinning
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
```

Dependabot-Update: **Aktualisiert auf den Commit-Hash der neuen Version.**

```yaml theme={null}
# 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.

```yaml theme={null}
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.

```yaml theme={null}
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.

<AccordionGroup>
  <Accordion title="Ersteinrichtung">
    * [ ] `.github/dependabot.yml` anlegen
    * [ ] Alle bestehenden Actions auf SHA pinnen
    * [ ] `pinact` oder manuelle Prüfung abgeschlossen
    * [ ] Erfolgreicher Workflow-Lauf verifiziert
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Audit">
    * [ ] Alle Action-Referenzen sind SHAs
    * [ ] Dependabot ist aktiv
    * [ ] Alle Dependabot-PRs der letzten 6 Monate sind gemergt
  </Accordion>
</AccordionGroup>

## Verwandte Seiten

<Columns cols={2}>
  <Card title="Grundlagen der Paketentwicklung" icon="box" href="/de/advanced/package-development">
    Wie Sie Laravel-Pakete rund um Service Provider entwickeln.
  </Card>

  <Card title="Versionskompatibilität von Paketen verwalten" icon="tag" href="/de/advanced/package-versioning">
    Strategien für Paket-Anpassungen bei Major-Upgrades von Laravel.
  </Card>
</Columns>


## Related topics

- [GitHub Actions - GitHub Copilot SDK für Laravel](/de/packages/laravel-copilot-sdk/github-actions.md)
- [Laravel Pint](/de/pint.md)
- [CHANGELOG und Release-Management für Pakete](/de/advanced/package-changelog.md)
- [Bot-Tutorial - Laravel Bluesky](/de/packages/laravel-bluesky/bot-tutorial.md)
- [Browser-Tests (Dusk)](/de/dusk.md)