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

# Pinning e sicurezza delle GitHub Actions

> Come contromisura agli attacchi supply chain sui pacchetti, come pinnare le dipendenze GitHub Actions da versione a hash SHA, inclusa la strategia di aggiornamento automatico via Dependabot.

Per contrastare i rischi di attacchi o manomissioni alle action di GitHub, il progetto ufficiale Laravel adotta il pinning delle GitHub Actions. Questa pagina illustra in modo pratico le contromisure di sicurezza che dovresti implementare come sviluppatore di pacchetti.

<Info>
  Questa pagina è la sorella di [Sviluppo di pacchetti Laravel](/it/advanced/package-development). Si presume una conoscenza di base di GitHub Actions.
</Info>

## Rischi di sicurezza delle GitHub Actions

### La pericolosità dei riferimenti basati su tag

Normalmente le GitHub Actions si referenziano tramite tag:

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

Problemi di questo approccio:

* **I tag sono mobili** — un tag può essere cancellato e ricreato mantenendo lo stesso nome
* **Rischio di manomissione** — se l'account del proprietario del repository viene compromesso, si può iniettare codice malevolo
* **Attacco supply chain** — un attacco a un'action da cui dipendi compromette il tuo workflow

### Come lo affrontano i progetti ufficiali Laravel

In [laravel/laravel](https://github.com/laravel/laravel) e [laravel/framework](https://github.com/laravel/framework) tutte le action sono pinnate a un commit hash (SHA).

```yaml theme={null}
# riferimento sicuro
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
```

## Strategia di implementazione del pinning

### Passo 1: creare il file di configurazione Dependabot

Nel repository del pacchetto crea `.github/dependabot.yml`. Puoi copiare quello di Laravel così com'è.

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

Il file svolge questi ruoli:

* **Scansione automatica** — cerca nuove versioni delle GitHub Actions
* **Creazione automatica di PR** — apre PR di aggiornamento quando c'è una novità
* **Controllo del metodo di aggiornamento** — aggiorna per versione le action non pinnate, per SHA quelle pinnate

### Passo 2: pinnare le action esistenti a SHA

Cambia tutti i riferimenti delle action nei workflow esistenti in hash SHA. Puoi automatizzarlo con strumenti come [pinact](https://github.com/suzuki-shunsuke/pinact).

#### Automazione con pinact

```shell theme={null}
# pinna a SHA le action nei workflow
pinact run
```

#### Modifiche manuali

Se non puoi usare `pinact`, consulta la pagina [Lookup latest version](https://github.com/actions/checkout) di GitHub per trovare gli SHA di ogni action e sostituiscili a mano.

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

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

### Passo 3: abilitare la configurazione Dependabot

Committa e pusha `.github/dependabot.yml`: Dependabot avvierà la scansione automaticamente.

## Meccanismo di aggiornamento automatico via Dependabot

Dependabot applica strategie diverse in base alle impostazioni di `dependabot.yml`.

### Action non pinnata

```yaml theme={null}
# prima del pinning
- uses: actions/checkout@v4
```

Aggiornamento Dependabot: **aggiorna il range di versione a quello nuovo**

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

Comoda ma con rischi di sicurezza residui: risponde al movimento del tag ma non protegge dalla manomissione.

### Action pinnata

```yaml theme={null}
# dopo il pinning
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
```

Aggiornamento Dependabot: **aggiorna al commit hash della nuova versione**

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

L'approccio più sicuro. Anche con una nuova versione, il riferimento è comunque un commit hash: molto più resistente alle manomissioni.

## Esempio completo di workflow

Esempio completo quando usi action in più workflow.

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

## Gestire le PR di aggiornamento Dependabot

Le PR di aggiornamento create da Dependabot si gestiscono così.

### PR di aggiornamento di una singola action

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

Aggiornamento semplice, procedi così:

1. Controlla il risultato dell'esecuzione del workflow
2. Verifica che non ci siano breaking change
3. Merge e chiudi

### PR di aggiornamento di sicurezza

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

Priorità massima per i fix di sicurezza: mergea per prima.

### Aggiornamenti raggruppati

Se in `dependabot.yml` hai impostato `groups`, più action vengono aggiornate in un'unica PR.

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

Raggruppare tutti gli aggiornamenti in una sola PR riduce il numero di merge.

## Vantaggi e svantaggi del pinning

### Vantaggi

| Vantaggio                     | Descrizione                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| **Contromisura supply chain** | Referenziando uno specifico commit hash, contrasti la manomissione delle action       |
| **Auditabilità**              | Puoi tracciare quando ogni action è stata aggiornata e da quale versione              |
| **Aggiornamenti espliciti**   | Dependabot propone gli aggiornamenti in PR, quindi passano sempre da una review umana |
| **Riproducibilità**           | Con lo stesso commit hash riottieni esattamente lo stesso ambiente                    |

### Svantaggi

| Svantaggio                                         | Come gestirlo                                                                |
| -------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Setup iniziale manuale**                         | Automatizza con lo strumento `pinact`                                        |
| **Maggior carico di gestione degli aggiornamenti** | Dependabot crea PR automaticamente, minimizzando il costo di implementazione |
| **Meno leggibilità**                               | Aggiungi commenti con la versione per la leggibilità                         |

## Checklist di audit di sicurezza

Checklist per l'avvio di un nuovo progetto pacchetto.

<AccordionGroup>
  <Accordion title="Setup iniziale">
    * [ ] Creare `.github/dependabot.yml`
    * [ ] Pinnare tutte le action esistenti a SHA
    * [ ] Aver completato la verifica con `pinact` o a mano
    * [ ] Verificare che i workflow si eseguano correttamente
  </Accordion>

  <Accordion title="Manutenzione periodica">
    * [ ] Rivedere le PR di aggiornamento Dependabot almeno una volta a settimana
    * [ ] Merge prioritari degli aggiornamenti di sicurezza
    * [ ] Referenziare sempre a SHA le action nuove
    * [ ] Una volta al mese verificare lo stato di tutti i workflow
  </Accordion>

  <Accordion title="Audit">
    * [ ] Verifica che tutti i riferimenti alle action siano su SHA
    * [ ] Verifica che Dependabot sia abilitato
    * [ ] Verifica che tutte le PR di Dependabot degli ultimi 6 mesi siano state mergeate
  </Accordion>
</AccordionGroup>

## Pagine correlate

<Columns cols={2}>
  <Card title="Nozioni di sviluppo dei pacchetti" icon="box" href="/it/advanced/package-development">
    Come sviluppare pacchetti Laravel imperniati sui service provider.
  </Card>

  <Card title="Gestire la compatibilità tra versioni dei pacchetti" icon="tag" href="/it/advanced/package-versioning">
    Strategie di adattamento dei pacchetti agli upgrade major di Laravel.
  </Card>
</Columns>


## Related topics

- [GitHub Actions - GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/github-actions.md)
- [Tutorial per bot - Laravel Bluesky](/it/packages/laravel-bluesky/bot-tutorial.md)
- [Tutorial - Laravel Console Starter](/it/packages/laravel-console-starter/tutorial.md)
- [Laravel Pint](/it/pint.md)
- [Test del browser (Dusk)](/it/dusk.md)