Configurare un flusso di lavoro di GitHub Actions

10 minuti

Verranno presentate alcune configurazioni comuni all'interno di un file di flusso di lavoro. Verranno inoltre illustrate le categorie dei tipi di evento, le procedure per disabilitare ed eliminare flussi di lavoro e l'utilizzo di versioni specifiche di un'azione per le procedure consigliate per la sicurezza.

Configurare flussi di lavoro da eseguire per eventi pianificati

Come accennato in precedenza, è possibile configurare i flussi di lavoro che devono essere eseguiti ogni volta che viene svolta un'attività specifica in GitHub, che si verifica un evento esterno a GitHub o a un'ora pianificata. L'evento schedule consente di attivare un flusso di lavoro in modo che venga eseguito a specifiche ore UTC usando la sintassi POSIX cron. Questa sintassi cron prevede cinque campi *, ognuno dei quali rappresenta un'unità di tempo.

Diagram of the five unit-of-time fields for scheduling an event in a workflow file.

Se ad esempio si vuole eseguire un flusso di lavoro ogni 15 minuti, l'evento schedule dovrà avere un aspetto simile al seguente:

on:
  schedule:
    - cron:  '*/15 * * * *'

Se invece si vuole eseguire un flusso di lavoro ogni domenica alle 3.00, l'evento schedule dovrà avere un aspetto simile al seguente:

on:
  schedule:
    - cron:  '0 3 * * SUN'

È inoltre possibile usare gli operatori per specificare un intervallo di valori o perfezionare il flusso di lavoro pianificato. L'intervallo più breve che è possibile specificare è pari a 5 minuti e i flussi di lavoro pianificati vengono eseguiti sul commit più recente nel ramo predefinito o di base.

Configurare flussi di lavoro da eseguire per eventi manuali

Oltre ad eseguire eventi pianificati, è possibile anche attivare manualmente un flusso di lavoro tramite l'evento workflow_dispatch. In particolare, questo evento consente di eseguire il flusso di lavoro usando l'API REST di GitHub oppure selezionando il pulsante Esegui flusso di lavoro nella scheda Azioni del repository su GitHub. workflow_dispatch consente di scegliere il ramo su cui eseguire il flusso di lavoro e di impostare inputs facoltativi che GitHub presenterà come elementi modulo nell'interfaccia utente.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

Oltre a usare workflow_dispatch, è possibile anche ricorrere all'API GitHub per attivare un evento webhook denominato repository_dispatch. Questo evento consente di attivare un flusso di lavoro per un'attività eseguita all'esterno di GitHub e svolge essenzialmente la funzione di richiesta HTTP per il repository richiedendo a GitHub di attivare un flusso di lavoro da un'azione o un webhook. Per usare questo evento manuale è necessario eseguire due operazioni: inviare una richiesta POST all'endpoint di GitHub /repos/{owner}/{repo}/dispatches con i nomi degli eventi webhook nel corpo della richiesta e configurare il flusso di lavoro in modo che usi l'evento repository_dispatch.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

Configurare flussi di lavoro da eseguire per eventi webhook

Infine, è possibile configurare un flusso di lavoro in modo che venga eseguito quando si verificano specifici eventi webhook in GitHub. La maggior parte degli eventi webhook può essere attivata da più di un'attività per webhook; se per un webhook esistono più attività, quindi, è possibile specificare un tipo di attività per l'attivazione del flusso di lavoro. È possibile, ad esempio, eseguire un flusso di lavoro per l'evento check_run ma solo per i tipi di attività rerequested o requested_action.

on:
  check_run:
    types: [rerequested, requested_action]

Usare parole chiave condizionali

Nel file del flusso di lavoro è possibile accedere alle informazioni di contesto e valutare le espressioni. Sebbene in un file del flusso di lavoro le espressioni vengano generalmente usate con la parola chiave condizionale if per determinare se un passaggio deve essere eseguito o meno, per creare un'istruzione condizionale è possibile usare qualsiasi contesto ed espressione supportati. È importante sapere che, se si usano istruzioni condizioni in un flusso di lavoro, è necessario usare la sintassi specifica ${{ <expression> }}, che indica a GitHub di valutare un'espressione anziché considerarla come una stringa.

Ad esempio, un flusso di lavoro che usa l'istruzione condizionale if per verificare se github.ref, il riferimento di ramo o tag che ha attivato l'esecuzione del flusso di lavoro, corrisponde a refs/heads/main per procedere con i passaggi successivi del flusso di lavoro, avrà un aspetto simile al seguente:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

Osservare come, in questo esempio, ${{ }} non siano presenti nella sintassi. Con alcune espressioni, come nel caso dell'istruzione condizionale if, è possibile omettere la sintassi dell'espressione. GitHub valuta automaticamente alcune di queste espressioni comuni, ma è sempre possibile includerle nel caso in cui non si ricordi quali espressioni sono state valutate automaticamente da GitHub.

Per altre informazioni sulla sintassi e sulle espressioni del flusso di lavoro, vedere Sintassi del flusso di lavoro per GitHub Actions.

Disabilitare ed eliminare flussi di lavoro

Dopo aver aggiunto un flusso di lavoro al repository, è possibile che si presenti una situazione per la quale è necessario disabilitare temporaneamente il flusso di lavoro. È possibile sospendere l'attivazione di un flusso di lavoro senza dover eliminare il file dal repository, sia in GitHub che tramite l'API REST di GitHub. Al momento desiderato, è possibile riabilitare il flusso di lavoro usando gli stessi metodi.

Screenshot of disabling a workflow on GitHub.

Disabilitare un flusso di lavoro può essere utile in varie situazioni, ad esempio:

Un errore in un flusso di lavoro sta generando troppe richieste o richieste errate che influiscono negativamente sui servizi esterni.
Si vuole sospendere temporaneamente un flusso di lavoro che non è essenziale e sta consumando troppi minuti sull'account.
Si vuole sospendere un flusso di lavoro che sta inviando richieste a un servizio non attivo.
Si sta lavorando a un fork e alcune funzionalità dei flussi di lavoro inclusi non sono necessarie (ad esempio, quelle dei flussi di lavoro pianificati).

È anche possibile annullare l'esecuzione di un flusso di lavoro in corso nell'interfaccia utente di GitHub dalla scheda Actions (Azioni) o tramite l'endpoint dell'API GitHub DELETE /repos/{owner}/{repo}/actions/runs/{run_id}. Tenere presente che, quando si annulla l'esecuzione di un flusso di lavoro, GitHub cancella tutti i relativi processi e passaggi.

Usare il flusso di lavoro basato su modelli di un'organizzazione

Se un flusso di lavoro viene usato da più team di un'organizzazione, anziché ricreare lo stesso flusso di lavoro per ogni repository, è possibile favorire la coerenza all'interno dell'organizzazione usando un modello di flusso di lavoro definito nel repository .github dell'organizzazione. Qualsiasi membro all'interno dell'organizzazione può usare un flusso di lavoro basato su modelli dell'organizzazione e a questi flussi può accedere qualsiasi repository all'interno dell'organizzazione.

Per trovare questi flussi di lavoro, passare alla scheda Actions (Azioni) di un repository all'interno dell'organizzazione, selezionare New workflow (Nuovo flusso di lavoro) e quindi cercare la sezione dei modelli di flussi di lavoro dell'organizzazione intitolata "Workflows created by (Flussi di lavoro creati da) nome organizzazione". L'organizzazione chiamata Mona, ad esempio, dispone del flusso di lavoro modello illustrato di seguito.

Screenshot of a template organization workflow called greet and triage by Mona.

Usare versioni specifiche di un'azione

Quando si fa riferimento a un'azione di un flusso di lavoro, è opportuno fare riferimento a una versione specifica dell'azione e non solo all'azione. In questo modo, infatti, si protegge l'azione da modifiche impreviste che potrebbero interrompere l'esecuzione del flusso di lavoro. Di seguito sono riportati alcuni modi in cui è possibile fare riferimento a una versione specifica di un'azione:

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

Alcuni riferimenti sono più sicuri di altri. Se, ad esempio, si fa riferimento a un ramo specifico, l'azione verrà eseguita senza le ultime modifiche apportate al ramo, nel caso in cui si preferisse escluderle. Facendo riferimento a uno specifico numero di versione o hash SHA di commit, sarà possibile essere più specifici sulla versione dell'azione da eseguire. Per maggiore stabilità e sicurezza, è consigliabile usare l'SHA di commit di un'azione rilasciata nell'ambito dei flussi di lavoro aziendali.

Continua