Testare le GitHub Actions in locale con act

Chi usa GitHub prima o poi si scontra con i workflow. Di recente stiamo affrontando una sfida solo all’apparenza banale: migrare alcuni dei nostri repo su Github e implementare le actions necessarie alle necessità di CI/CD.

Di base sarebbe banale, in rete ci sono gazilioni di esempi, template, guide e perfino wizard che, in teoria, ti forniscono gli script già pronti.

Migrando uno degli ultimi repo però mi è successa una cosa particolare. Stavo usando per il workflow da eseguire sulle pull-request lo stesso script usato con successo in altri repo (sono tutti sistemi basati su Laravel). Questa volta però non andava, errori di connessione al db, test che fallivano in maniera inaspettata.

Tentavo le correzioni, push su GitHub, interminabile attesa che il workflow girasse per esaminare gli errori.

Un modo mooolto lento di procedere.

Installare e usare act per testare le GitHub Actions

Per fortuna c’è un’alternativa: act - https://nektosact.com/ questa fantastica utility scritta in Go permette di eseguire le actions di GitHub in locale grazie alla creazione al volo di una serie di container (nel mio caso uso Podman invece di Docker).

L’installazione è banale, nel mio caso su Mac

brew install act

Dopodiché basta avere il servizio Docker (o Podman) attivo e lanciare l’utility.

Ecco un esempio completo di comando, con tutti i parametri che uso nel mio ambiente:

act \
  --workflows ".github/workflows/main.yml" \
  --secret-file .secrets \
  --var-file .vars \
  --pull=false \
  --container-architecture linux/arm64 \
  -P ubuntu-latest=catthehacker/ubuntu:act-latest \
  -P self-hosted=catthehacker/ubuntu:act-latest

Configurare act: i parametri principali

Vi spiego i vari parametri:

Parametro	Descrizione
`--workflows`	Path del file `.yml` del workflow da eseguire
`--secret-file`	Variabili SECRET in formato `NOME=valore` (una per riga)
`--var-file`	Variabili VARIABLE in formato `NOME=valore` (una per riga)
`--pull`	Se `false`, evita di scaricare ogni volta l’immagine del container
`--container-architecture`	Architettura da usare per i container (es. `linux/arm64`)
`-P`	Specifica l’immagine da usare per il container che eseguirà il workflow

Nel mio caso per il container ho scelto catthehacker/ubuntu:act-latest rispetto a catthehacker/ubuntu:full-latest perché quest’ultima, anche se ha la massima compatibilità integrando praticamente tutti i tool necessari, è enorme (60Gb una volta estratta) e non era necessaria.

Conclusioni: perché usare act

Utilizzare act mi ha permesso di testare molto più velocemente il workflow, individuare i problemi e correggerlo in una frazione del tempo rispetto al classico edit->commit->push->execute action->repeat

Un’ultima cosa. Una volta messo a punto il workflow, girava perfettamente su act, è successo che alcuni test fallissero una volta che il workflow veniva eseguito su GitHub. La spiegazione è tanto banale quanto insidiosa: act, ma anche un banale php artisan test useranno il vostro file .env se presente. Tenetene conto quando scrivete il workflow.

Nota importante ⚠️
act utilizza il file .env locale per eseguire i test, mentre GitHub Actions potrebbe avere un contesto diverso.
Assicurati di configurare correttamente le variabili d’ambiente nel workflow per evitare comportamenti inattesi.