> ## 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 pinnen en beveiliging

> Leer hoe je als maatregel tegen supply-chain-aanvallen de dependencies van GitHub Actions pint van versies naar SHA-hashes, inclusief een strategie voor automatische updates met Dependabot.

Om het risico van aanvallen op en manipulatie van GitHub-actions af te dekken, is het pinnen van GitHub Actions een beveiligingsmaatregel die ook de officiële Laravel-projecten toepassen. Op deze pagina leggen we praktisch uit welke beveiligingsmaatregelen je als pakketontwikkelaar zou moeten implementeren.

<Info>
  Deze pagina is een zusterpagina van [Basis van pakketontwikkeling](/nl/advanced/package-development). We gaan ervan uit dat je bekend bent met het basisgebruik van GitHub Actions.
</Info>

## Beveiligingsrisico's van GitHub Actions

### Het gevaar van verwijzen via tags

Normaal gesproken worden GitHub Actions als volgt via tags gerefereerd.

```yaml theme={null}
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
```

De problemen met deze aanpak:

* **Tags zijn verplaatsbaar** — een tag kan worden verwijderd en opnieuw aangemaakt onder dezelfde naam
* **Manipulatierisico** — via een overgenomen account van de repository-eigenaar kan kwaadaardige code worden geïnjecteerd
* **Supply-chain-aanvallen** — als een action waarvan je afhankelijk bent wordt aangevallen, is jouw workflow gecompromitteerd

### Hoe de officiële Laravel-projecten dit aanpakken

In [laravel/laravel](https://github.com/laravel/laravel) en [laravel/framework](https://github.com/laravel/framework) zijn alle actions gepind op commithashes (SHA).

```yaml theme={null}
# Veilige manier van refereren
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
```

## Implementatiestrategie voor pinnen

### Stap 1: het Dependabot-configuratiebestand aanmaken

Maak in de repository van je pakket het bestand `.github/dependabot.yml` aan. Je kunt het bestand van Laravel gewoon kopiëren.

```yaml theme={null}
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 5
    groups:
      github-actions:
        patterns:
          - "*"
```

Dit bestand vervult de volgende rollen:

* **Automatisch scannen** — scant op nieuwe versies van GitHub Actions
* **Automatisch PR's aanmaken** — maakt automatisch een update-PR aan als er een update beschikbaar is
* **De updatemethode sturen** — niet-gepinde actions worden per versie geüpdatet, gepinde actions per SHA

### Stap 2: bestaande actions pinnen op SHA

Verander alle action-referenties in je bestaande workflows naar SHA-hashes. Dit kun je automatiseren met tools zoals [pinact](https://github.com/suzuki-shunsuke/pinact).

#### Automatiseren met de pinact-tool

```shell theme={null}
# Actions in workflows pinnen op SHA
pinact run
```

#### Handmatig aanpassen

Als `pinact` niet beschikbaar is, zoek je de commit-SHA van elke action op via de GitHub-pagina [Lookup latest version](https://github.com/actions/checkout) en vervang je ze handmatig.

```yaml theme={null}
# Vóór de wijziging
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
  with:
    php-version: ${{ matrix.php }}

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

### Stap 3: de Dependabot-configuratie activeren

Zodra je `.github/dependabot.yml` naar de repository commit en pusht, begint Dependabot automatisch te scannen.

## Het automatische updatemechanisme van Dependabot

Dependabot past op basis van de instellingen in `dependabot.yml` verschillende updatestrategieën toe.

### Niet-gepinde actions

```yaml theme={null}
# Vóór het pinnen
- uses: actions/checkout@v4
```

Update door Dependabot: **de versierange wordt bijgewerkt naar een nieuwe versie**

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

Deze aanpak is gericht op gemak en kan omgaan met verplaatste tags, maar het beveiligingsrisico blijft bestaan.

### Gepinde actions

```yaml theme={null}
# Na het pinnen
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
```

Update door Dependabot: **wordt bijgewerkt naar de commithash van de nieuwe versie**

```yaml theme={null}
# PR die Dependabot aanmaakt
- uses: actions/checkout@f1d3225b54b677ba3e72df8c464cb6cf6dc1aebf  # v4
```

Deze aanpak is het veiligst. Ook bij een nieuwe versie verwijs je naar een commithash en ben je dus bestand tegen manipulatie.

## Voorbeeldimplementatie van workflows

Een compleet voorbeeld voor wanneer je actions in meerdere workflows gebruikt.

```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
```

## Omgaan met update-PR's van Dependabot

De update-PR's die Dependabot aanmaakt, handel je als volgt af.

### Update-PR voor een enkele action

```
Bump shivammathur/setup-php from v1 to v2
```

Zo'n eenvoudige update pak je als volgt aan:

1. Controleer het resultaat van de workflowrun
2. Controleer op breaking changes
3. Merge en klaar

### Beveiligingsupdate-PR

```
[SECURITY] Bump actions/checkout to a5ac7e51b41094c7fcab2042361574b0021804ab
```

Updates die een beveiligingsfix betreffen, merge je met voorrang.

### Gegroepeerde updates van meerdere actions

Als je `groups` hebt geconfigureerd in `dependabot.yml`, worden meerdere actions in één PR geüpdatet.

```yaml theme={null}
groups:
  github-actions:
    patterns:
      - "*"
```

Door alle action-updates in één PR te bundelen, verminder je het aantal merges.

## Voor- en nadelen van pinnen

### Voordelen

| Voordeel                                     | Toelichting                                                                                      |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Bescherming tegen supply-chain-aanvallen** | Omdat je naar een specifieke commithash verwijst, ben je bestand tegen manipulatie van de action |
| **Auditbaarheid**                            | Je kunt traceren wanneer en vanaf welke versie elke action is geüpdatet                          |
| **Expliciete updates**                       | Omdat Dependabot updates voorstelt, gaat er altijd een menselijke review overheen                |
| **Reproduceerbaarheid**                      | Met dezelfde commithash krijg je exact dezelfde omgeving terug                                   |

### Nadelen

| Nadeel                        | Oplossing                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------- |
| **Handmatige initiële setup** | Automatiseer met de `pinact`-tool                                                  |
| **Meer updatebeheer**         | Dependabot maakt automatisch PR's aan, dus de implementatiekosten blijven minimaal |
| **Slechtere leesbaarheid**    | Zet de versie in een comment ernaast voor leesbaarheid                             |

## Checklist voor beveiligingsaudits

Een checklist voor wanneer je een nieuw pakketproject start.

<AccordionGroup>
  <Accordion title="Initiële setup">
    * [ ] `.github/dependabot.yml` aangemaakt
    * [ ] Alle bestaande actions gepind op SHA
    * [ ] Gecontroleerd met `pinact` of handmatig
    * [ ] Gecontroleerd dat de workflows correct draaien
  </Accordion>

  <Accordion title="Periodiek onderhoud">
    * [ ] Update-PR's van Dependabot minstens wekelijks reviewen
    * [ ] Beveiligingsupdates met voorrang mergen
    * [ ] Nieuwe actions altijd via SHA refereren
    * [ ] Eén keer per maand de status van alle workflows controleren
  </Accordion>

  <Accordion title="Audit">
    * [ ] Controleren of alle action-referenties SHA's zijn
    * [ ] Controleren of Dependabot is ingeschakeld
    * [ ] Controleren of alle Dependabot-PR's van de afgelopen 6 maanden zijn gemerged
  </Accordion>
</AccordionGroup>

## Gerelateerde pagina's

<Columns cols={2}>
  <Card title="Basis van pakketontwikkeling" icon="box" href="/nl/advanced/package-development">
    Leer hoe je Laravel-pakketten ontwikkelt met service providers als kern.
  </Card>

  <Card title="Versiecompatibiliteit van pakketten beheren" icon="tag" href="/nl/advanced/package-versioning">
    Leer strategieën om je pakket mee te laten gaan met major versie-upgrades van Laravel.
  </Card>
</Columns>


## Related topics

- [GitHub Actions - GitHub Copilot SDK voor Laravel](/nl/packages/laravel-copilot-sdk/github-actions.md)
- [Bottutorial - Laravel Bluesky](/nl/packages/laravel-bluesky/bot-tutorial.md)
- [Laravel Pint](/nl/pint.md)
- [Tutorial - Laravel Console Starter](/nl/packages/laravel-console-starter/tutorial.md)
- [CHANGELOG en releasebeheer voor packages](/nl/advanced/package-changelog.md)