GitHub Actions: buone pratiche

Questo documento in lavorazione raccoglie una serie di buone pratiche per usare GitHub Actions. Se hai suggerimenti o vuoi aggiungere qualcosa, apri una pull request su GitHub!

• GitHub Actions: buone pratiche
  • Raccolta di buone pratiche
    • Impostare i timeout per i workflow
      • Esempio
    • Valutare se le action (di terze parti) sono davvero necessarie
    • Limitare lo scope del token del workflow
      • Esempio
    • Fissare le action a uno SHA
      • Trovare lo SHA del commit
      • Esempio
    • Fissare i test runner a una versione
      • Esempio
    • Valutare se impostare una strategia di concurrency
      • Esempio
    • Valutare quali trigger sono davvero necessari
    • Leggere la guida "Security hardening for GitHub Actions"
  • Checklist del workflow

Raccolta di buone pratiche

Impostare i timeout per i workflow

Per impostazione predefinita, GitHub Actions interrompe i workflow dopo 6 ore, se non sono ancora terminati. Molti workflow non hanno bisogno di tutto questo tempo per concludersi, ma a volte si verificano errori imprevisti oppure un job resta bloccato finché l'esecuzione del workflow non viene interrotta 6 ore dopo l'avvio. Per questo motivo è consigliabile specificare un timeout più breve.

Il timeout ideale dipende dal singolo workflow, ma 30 minuti sono di solito più che sufficienti per i workflow usati nei repository di Exercism.

Questo offre i seguenti vantaggi:

• Le PR non restano in attesa della CI per mezza giornata: i problemi si possono individuare subito e le esecuzioni del workflow si possono riavviare.
• Il numero complessivo di build parallele è limitato: i job bloccati non creano problemi alle altre PR, se vengono annullati per tempo.

Esempio

jobs:
  configlet:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - [...]

Valutare se le action (di terze parti) sono davvero necessarie

Le action vanno trattate come le dipendenze del tuo linguaggio di programmazione preferito¹: sono codice scritto da autori di terze parti, al di fuori del controllo di Exercism. Anche se ti fidi degli autori dell'action, il repository potrebbe essere oggetto di una scalata ostile, che indirettamente darebbe a quelle persone accesso ai repository di Exercism, incluso l'accesso in scrittura.

Perciò dovresti valutare con attenzione se introdurre una nuova action valga davvero la pena, o se sia meglio spostare il codice in una (nuova) action sotto il controllo di Exercism.

Considera anche se l'action è mantenuta attivamente, ad esempio controllando l'attività recente del repository o verificando che l'action appartenga a un'organizzazione e non a un account personale.

Le action pubblicate da GitHub o dall'organizzazione di Exercism si possono generalmente considerare sicure (più o meno) e includerle senza particolari accorgimenti.

Limitare lo scope del token del workflow

Per impostazione predefinita, il token di accesso assegnato al workflow ha permessi molto ampi, sia in lettura che in scrittura.

Anche ai workflow va applicato il principio del minimo privilegio.

Puoi specificare quali permessi serve a un workflow per singolo workflow.

Esempio

Se un workflow deve solo leggere il contenuto di un repository e non scriverci, ad esempio perché è un normale controllo della CI, puoi limitare il token in questo modo:

permissions:
  contents: read

Consulta la documentazione di GitHub per l'elenco completo dei permessi.

Fissare le action a uno SHA

Quando usi altre action, fissale a un commit (tramite il suo SHA), non a un branch o a un tag. Così sei sicuro che venga eseguito sempre lo stesso codice, cosa che non è garantita se fissi un branch o un tag.

Questo offre due vantaggi:

1. Rende la tua build stabile
2. Impedisce a un malintenzionato di modificare un branch o un tag per farlo puntare a codice malevolo

L'unica eccezione a questa regola potrebbero essere le action che abbiamo creato noi (Exercism).

Trovare lo SHA del commit

Di solito conviene fissare lo SHA del commit di una release specifica. Per trovare lo SHA del commit di una release, vai alla pagina delle release del repository dell'action (ad esempio https://github.com/actions/checkout/releases). Trova la release che vuoi usare e fai clic sullo SHA abbreviato (ad esempio a12a394) che compare nella sezione di riepilogo a sinistra della release. Verrai reindirizzato alla pagina dei dettagli della release, dove è elencato lo SHA completo del commit che puoi usare.

Esempio

- name: Checkout code
  uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846

Fissare i test runner a una versione

La maggior parte dei workflow viene eseguita sui runner supportati da GitHub. Quando usi uno di questi runner, indica una versione specifica invece della versione più recente.

Così il workflow viene sempre eseguito sullo stesso runner, il che rende la tua build stabile.

Esempio

Usa:

runs-on: ubuntu-22.04

invece di:

runs-on: ubuntu-latest

Valutare se impostare una strategia di concurrency

Spesso non è necessario né utile eseguire la CI sui commit intermedi, se nel frattempo è stato inviato un commit più recente.

Puoi configurare una strategia di concurrency per annullare automaticamente i workflow in esecuzione nello stesso contesto.

Esempio

Per annullare le build intermedie in una PR, puoi usare le seguenti impostazioni di concurrency:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

Valutare quali trigger sono davvero necessari

Leggere la guida "Security hardening for GitHub Actions"

Le pratiche appena viste non sono certo esaustive. Per una guida completa sulle buone pratiche di sicurezza per usare GitHub Actions in modo sicuro, dai un'occhiata alla guida alla sicurezza di GitHub.

Checklist del workflow

Puoi usare la checklist seguente per verificare se un workflow segue le buone pratiche. La checklist non vuole essere completa, ma si concentra sugli elementi più importanti.