Configurare un flusso di lavoro di GitHub Actions

Completato

In questa sezione vengono illustrate alcune configurazioni comuni all'interno di un file del flusso di lavoro. È anche possibile esplorare le categorie di tipi di evento, disabilitare ed eliminare flussi di lavoro e usare 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.

Ad esempio, se si vuole eseguire un flusso di lavoro ogni 15 minuti, l'evento schedule sarà simile all'esempio 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. Usando workflow_dispatch, puoi scegliere su quale ramo vuoi eseguire il flusso di lavoro e impostare le opzioni facoltative inputs che GitHub presenta come elementi del modulo del form 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 l'attività che si verifica all'esterno di GitHub. Essenzialmente funge da richiesta HTTP al repository in cui viene chiesto 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. È possibile attivare la maggior parte degli eventi webhook da più attività per un webhook. Se esistono più attività per un webhook, è possibile specificare un tipo di attività per attivare il flusso di lavoro. Ad esempio, è possibile eseguire un flusso di lavoro per l'evento check_run , ma solo per i rerequested tipi di attività o requested_action .

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch è un evento personalizzato in GitHub Actions che consente ai sistemi esterni (o anche ad altri flussi di lavoro GitHub) di attivare manualmente i flussi di lavoro inviando una richiesta POST all'API GitHub. Consente l'automazione e l'integrazione flessibili con strumenti, script o sistemi esterni che devono avviare flussi di lavoro nel repository.

Casi d'uso

• Attivare flussi di lavoro da strumenti CI/CD esterni.

• Coordinare le distribuzioni di più repository, ad esempio Repo A termina la compilazione → Attiva Repo B.

• Avviare l'automazione in base a eventi esterni (webhook, avvisi di monitoraggio, processi CRON all'esterno di GitHub).

• Concatenare le esecuzioni del flusso di lavoro tra repository o all'interno di monorepos.

Flusso di lavoro di esempio in ascolto di repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

Elementi chiave:

• tipi: facoltativo. Definisce tipi di evento personalizzati come run-tests, deploy-to-prode così via.

• github.event.client_payload: accesso a qualsiasi altro dato personalizzato passato nell'evento dispatch.

• github.event.action: nome del event_type inviato.

Attivazione dell'evento tramite API

È necessario inviare una richiesta POST all'endpoint dell'API REST di GitHub v3:

POST https://api.github.com/repos/OWNER/REPO/dispatches

Autorizzazione

• Richiede un token di accesso personale con ambito repository.
• Per le organizzazioni, verificare le impostazioni di accesso appropriate per il token.

Struttura dei comandi di esempio

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

Struttura del payload

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

Parametri

Campo	TIPO	Descrizione	Obbligatorio
event_type	string	Nome personalizzato per l'evento. Questo nome esegue il mapping al valore dei tipi nel trigger del flusso di lavoro	Sì
client_payload	oggetto	Payload JSON arbitrario per inviare dati personalizzati al flusso di lavoro (github.event.client_payload)	NO

Suddivisione dei parametri di Repository_dispatch

Quando si effettua una richiesta POST all'endpoint dell'API GitHub, è necessario passare un corpo JSON con due parametri principali:

• tipo_di_evento
• client_payload

tipo_di_evento

Stringa personalizzata richiesta definita dall'utente. GitHub considera questo valore come "azione" o "tipo" del dispatch. Viene usato per identificare i flussi di lavoro attivati e filtrare i flussi di lavoro in ascolto di tipi specifici.

• Formato:

  • Tipo: string
  • Esempio: "deploy", "run-tests", "sync-db", "build-docker"

• Utilizzo nel flusso di lavoro: utilizzato per ascoltare tipi di eventi specifici e accedere al valore all'interno del flusso di lavoro. Ciò consente il riutilizzo di un singolo flusso di lavoro per più scopi e rende l'automazione più organizzata e guidata dagli eventi.

• Esempio:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

Oggetto JSON in formato libero che consente di inviare dati personalizzati insieme all'invio. Definisci la struttura, e sarà accessibile all'interno del flusso di lavoro.

• Formato:

  • Tipo: oggetto
  • Chiavi e valori personalizzati

• Uso nei Workflow: questo oggetto viene usato per distribuzioni multi-ambiente, rilasci versionati o trasferimento di contesto da un altro sistema o pipeline e consente flussi di lavoro parametrizzati, simili agli argomenti di input.

• Esempio:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

Suddivisione del payload di esempio

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

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 quando si usano le istruzioni condizionali nel flusso di lavoro, è necessario usare la sintassi ${{ <expression> }}specifica . Questa sintassi indica a GitHub di valutare un'espressione anziché considerarla come stringa.

Ad esempio, un flusso di lavoro che usa l'istruzione if condizionale per verificare se ( github.ref il ramo o il riferimento tag che ha attivato l'esecuzione del flusso di lavoro) corrisponde a refs/heads/main. Per procedere, il flusso di lavoro sarà 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, ad esempio l'istruzione if condizionale, è 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.

La disabilitazione di un flusso di lavoro può essere utile in alcune delle situazioni seguenti:

• 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 un'esecuzione del flusso di lavoro, GitHub annulla tutti i processi e i passaggi all'interno di tale esecuzione.

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

Se si dispone di un flusso di lavoro usato da più team all'interno di un'organizzazione, non è necessario ricreare lo stesso flusso di lavoro per ogni repository. È invece possibile promuovere la coerenza nell'organizzazione usando un modello di flusso di lavoro definito nel repository dell'organizzazione .github . 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". Ad esempio, l'organizzazione denominata Mona ha un flusso di lavoro modello, come illustrato di seguito.

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. Ad esempio, fare riferimento a un ramo specifico esegue quell'azione in base alle ultime modifiche di quel ramo, il che potrebbe essere desiderabile o meno. 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.