Gestire ed eseguire il debug dei flussi di lavoro in GitHub Actions

10 minuti

Tenere presente che l'obiettivo è automatizzare il processo di compilazione e pubblicazione del codice in modo che le funzionalità vengano aggiornate ogni volta che uno sviluppatore aggiunge una modifica alla codebase.

Per implementare questo processo, si apprenderà come:

Identificare l'evento che ha attivato un flusso di lavoro.
Usare i log del flusso di lavoro di GitHub Actions.
Salva e accedi ai file di build.
Automatizzare l'aggiunta di un'etichetta a una richiesta pull dopo una revisione.

Identificare l'evento che ha attivato un flusso di lavoro

Comprendere cosa ha attivato un flusso di lavoro di GitHub Actions è fondamentale per il debug, il controllo e il miglioramento delle pipeline CI/CD. Tipi di trigger includono un push su una diramazione, una richiesta pull creata o aggiornata, un processo pianificato o un intervento manuale. È possibile identificare l'evento di attivazione esaminando l'esecuzione del flusso di lavoro, le modifiche del repository e il problema o la richiesta pull di GitHub correlata.

Diagramma che mostra vari trigger del flusso di lavoro in GitHub Actions, ad esempio push, richiesta pull, pianificazione e invio manuale.

Che cos'è un trigger del flusso di lavoro?

Un trigger del flusso di lavoro è un evento che causa l'esecuzione di un flusso di lavoro. GitHub supporta diversi tipi di trigger, tra cui:

push o pull_request (in base alle modifiche al codice)
workflow_dispatch (un attivatore manuale)
schedule (processi Cron)
repository_dispatch (sistemi esterni)
Eventi di segnalazione, discussione e pull request (ad esempio, issues.opened, pull_request.closed)

Identificare l'evento attivatore

È possibile identificare un evento trigger del flusso di lavoro in diversi modi:

Usare l'interfaccia utente di GitHub Actions:
1. Nel repository selezionare la scheda Azioni .
2. Selezionare l'esecuzione di un flusso di lavoro.
Nella parte superiore del riepilogo dell'esecuzione del flusso di lavoro viene visualizzato un tipo di evento, ad esempio push, pull_requesto workflow_dispatch.
Usare github.event_name nei log o in un flusso di lavoro.
- GitHub espone i dati di contesto durante un'esecuzione del flusso di lavoro. La github.event_name variabile indica quale evento ha attivato il flusso di lavoro.
- È possibile stampare le informazioni in un passaggio per il debug:
```
-name: Show event trigger
  run: echo "Triggered by ${{ github.event_name }}"
```
Usare i dettagli dell'esecuzione del flusso di lavoro:
- Se si esaminano le esecuzioni del flusso di lavoro a livello di codice, ad esempio tramite l'API, l'oggetto run include una event proprietà che specifica il trigger.
- È possibile trovare il commit Secure Hash Algorithm (SHA), l'attore e il timestamp per tracciare ciò che ha causato il trigger.

Dedurre il trigger dagli effetti del repository

Potrebbe non avere accesso diretto all'esecuzione del flusso di lavoro, ma si vuole comunque dedurre ciò che ha attivato l'esecuzione del flusso di lavoro in base all'attività del repository:

Comportamento osservato	Evento di attivazione
È stato eseguito il push di un nuovo commit in `main` e il flusso di lavoro è stato eseguito.	`push` evento
Una richiesta di pull è stata aperta o aggiornata.	`pull_request` evento
Un collaboratore ha eseguito manualmente un flusso di lavoro.	`workflow_dispatch`
Il flusso di lavoro viene eseguito ogni giorno in un momento specifico.	`schedule` (Cron)
Il flusso di lavoro è stato eseguito dopo una chiamata al servizio esterno.	`repository_dispatch`
Il flusso di lavoro è stato eseguito quando un'etichetta o un commento è stato aggiunto a una questione.	`issues.*` evento

Esaminando i timestamp, l'attività della richiesta pull e la cronologia dei commit, è spesso possibile individuare l'azione che ha causato l'esecuzione del flusso di lavoro.

Per riepilogare come identificare ciò che ha attivato un flusso di lavoro:

Controllare il riepilogo dell'esecuzione del flusso di lavoro nella scheda Azioni .
Stampare o registrare github.event_name all'interno del flusso di lavoro per garantirne la visibilità.
Confrontare timestamp e attività del repository (commit, richieste pull, problemi) per dedurre il trigger.
Usare il contesto completo event per un'analisi più approfondita.

Queste procedure consentono di eseguire il debug, il controllo e migliorare l'affidabilità del flusso di lavoro nelle pipeline di sviluppo e distribuzione.

Comprendere l'effetto del flusso di lavoro leggendo il file di configurazione

Per comprendere gli effetti di un flusso di lavoro dalla lettura del file di configurazione, analizzare la struttura e il contenuto del .yml file archiviato in .github/workflows/.

Il file di configurazione del flusso di lavoro specifica le informazioni seguenti sul flusso di lavoro:

Quando viene eseguito (nella sezione on).
Che cosa fa (in jobs e steps).
Quando viene eseguito (la sezione runs-on).
Perché viene eseguito (scopo, ad esempio test, distribuzione o linting).
Come si comporta in condizioni specifiche (ambiente, filtri, logica).

Interpretare l'effetto di un flusso di lavoro

Identificare il fattore scatenante.

Per identificare l'azione avviata dal flusso di lavoro, vedere la on sezione del flusso di lavoro.

Per esempio:
```
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
  workflow_dispatch:
```
Questo flusso di lavoro di esempio:
- Si esegue automaticamente quando il codice viene inviato al ramo principale (push).
- Viene eseguito quando viene creata o aggiornata una richiesta pull (pull_request).
- Può essere attivato manualmente da un utente (workflow_dispatch).
Identificare i processi e i passaggi del flusso di lavoro.

Per determinare le operazioni del flusso di lavoro, vedere le sezioni jobs e steps del flusso di lavoro.

Per esempio:
```
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test
```
Questo flusso di lavoro di esempio:
- Usa un ambiente virtuale Linux (runs-on).
- Estrae il codice del repository (steps>name).
- Installa le dipendenze del progetto (steps>name).
- Esegue test automatizzati (steps>name).
Valutare lo scopo e il risultato del flusso di lavoro.

Leggendo il file di configurazione, è possibile descrivere il risultato previsto del flusso di lavoro:

"Questo flusso di lavoro è una pipeline di integrazione continua (CI). Garantisce che qualsiasi nuovo codice di cui viene eseguito il push nel repository o inviato tramite richiesta pull venga testato automaticamente. Se i test hanno esito negativo, l'interfaccia utente del flusso di lavoro di GitHub visualizza questo risultato per mantenere la qualità del codice."
Identificare o impostare funzionalità facoltative che influiscono sulla modalità di esecuzione del flusso di lavoro:
- env imposta le variabili di ambiente.
- if aggiunge la logica condizionale per eseguire passaggi specifici solo quando vengono soddisfatti i criteri.
- timeout-minutes o continue-on-error impostare l'esecuzione del flusso di lavoro e la gestione degli errori.

Diagnosticare un'esecuzione del flusso di lavoro non riuscita

Nel repository, vai alla scheda Azioni.
Trovare l'esecuzione non riuscita (in genere indicata da una X rossa).
Selezionare il flusso di lavoro non riuscito per aprire il riepilogo dell'esecuzione.
Nei log del flusso di lavoro esaminare l'errore.
1. Nel riepilogo dell'esecuzione, espandere ogni processo e passaggio fino a trovare quello che indica l'errore.
2. Selezionare il processo o il passaggio per visualizzarne i log.
3. Cercare:
  - Messaggi di errore
  - Tracce di stack
  - Codici di uscita
Ad esempio, un test non riuscito potrebbe mostrare npm ERR! Test failed o exit code 1.
Controllare il file di configurazione del flusso di lavoro.

Usare il .yml file per determinare:
- Qual era lo scopo di ciascun passaggio?
- Se sono presenti variabili di ambiente (env) o condizionali (if) che influiscono sull'esecuzione.
- Se l'errore è causato da una dipendenza mancante, un errore di sintassi o da un passaggio configurato in modo errato.
Se un passaggio non riesce, verificare le cause seguenti:
- Le dipendenze sono state installate correttamente nel passaggio precedente?
- I file di test esistono e passano localmente?

Scenari di errore comuni

La tabella seguente descrive gli scenari comuni di errore del flusso di lavoro:

Sintomo	Causa possibile
Un passaggio ha esito negativo e restituisce `command not found`l	Dipendenza mancante o configurazione errata
`npm install` fallisce.	File danneggiato `package-lock.json` o problema di rete
Un passaggio di test ha esito negativo	Problemi di unit test, file di configurazione mancanti o sintassi di test non valida
`Permission denied` appare.	Autorizzazioni file non corrette o segreti mancanti

Identificare come accedere ai log del flusso di lavoro in GitHub

Nel repository, vai alla scheda Azioni.
Nell'elenco dei flussi di lavoro selezionare il flusso di lavoro pertinente.

Ad esempio, se il .yml file ha il codice seguente, viene visualizzato un collegamento denominato CI Workflow nell'elenco:
```
name: CI Workflow
```
Seleziona un'esecuzione specifica.

Nell'elenco di esecuzioni che mostrano lo stato selezionare il timestamp o il messaggio di commit dell'esecuzione specifica da esaminare.
Espandere ogni processo e passaggio.

La pagina di riepilogo dell'esecuzione visualizza i processi definiti nel file del flusso di lavoro, ad esempio compilazione o test:
1. Seleziona un lavoro per espanderlo.
2. All'interno del processo, espandere singoli passaggi, ad esempio "Installa dipendenze" o "Esegui test".
Visualizzare l'output del log.

Per visualizzare l'output completo del log, inclusi i log della console, i messaggi di errore e le informazioni di debug, selezionare un passaggio del flusso di lavoro. È possibile copiare, cercare e scaricare i log.

La tabella seguente riepiloga i passaggi da eseguire per accedere ai log del flusso di lavoro:

Azione	Scopo
Scheda Azioni	Visualizzare tutte le esecuzioni del flusso di lavoro.
Selezionare il nome del flusso di lavoro	Filtrare le esecuzioni in base al flusso di lavoro.
Selezionare un'esecuzione	Visualizza i risultati specifici del lavoro e dei passaggi.
Espandere i passaggi	Visualizzare i log dettagliati.
Scaricare i log	Scaricare i log per la risoluzione dei problemi offline o del team.

Log delle azioni per la compilazione

Quando viene eseguito un flusso di lavoro, viene generato un log che include i dettagli di ciò che è accaduto e gli eventuali errori o errori di test.

Se si verifica un errore o se un test ha esito negativo, nei log viene visualizzato un segno di spunta rosso X anziché un segno di spunta verde. È possibile esaminare i dettagli dell'errore o del guasto per indagare su ciò che è successo.

Screenshot del log di GitHub Actions con i dettagli di un test non riuscito.

Usare gli artefatti

Quando un flusso di lavoro produce un elemento diverso da una voce di log, il prodotto viene chiamato artefatto. Ad esempio, la compilazione Node.js produce un contenitore Docker che può essere distribuito. Il contenitore è un artefatto che è possibile caricare nella risorsa di archiviazione usando l'azione actions/upload-artifact . In seguito è possibile scaricare l'artefatto dall'archiviazione usando azioni/download-artifact.

L'archiviazione di un artefatto permette di conservarlo tra un processo e l'altro. Ogni processo usa una nuova istanza di una macchina virtuale, quindi non è possibile riutilizzare l'artefatto salvandolo nella macchina virtuale. Se è necessario l'elemento in un processo diverso, è possibile caricare l'artefatto nell'archiviazione in un processo e scaricarlo per l'altro processo.

Archiviazione di artefatti

Gli artefatti vengono archiviati nello spazio di archiviazione in GitHub. Lo spazio è disponibile per i repository pubblici e alcune risorse di archiviazione sono gratuite per i repository privati, a seconda dell'account. GitHub archivia gli artefatti per 90 giorni.

Nel frammento di flusso di lavoro seguente si noti che nell'azione actions/upload-artifact@main è presente un path attributo . Il valore di questo attributo è il percorso in cui archiviare l'artefatto. In questo esempio si specifica public/ per caricare tutti gli elementi in una directory. Se si vuole caricare solo un singolo file, usare un file come public/mytext.txt.

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@main
        with:
          name: webpack artifacts
          path: public/

Per scaricare l'artefatto per il test, la compilazione deve essere completata correttamente e caricare l'artefatto. Nel codice seguente si specifica che il processo di test dipende dal processo di compilazione.

test:
    needs: build
    runs-on: ubuntu-latest

Nel frammento di flusso di lavoro seguente si scarica l'artefatto. Ora il processo di testing può usare l'artefatto per il testing.

steps:
    - uses: actions/checkout@v3
    - uses: actions/download-artifact@main
      with:
        name: webpack artifacts
        path: public

Per altre informazioni sull'uso degli artefatti nei flussi di lavoro, vedere Archiviazione dei dati del flusso di lavoro come artefatti.

Automatizzare le revisioni in GitHub usando i flussi di lavoro

Oltre ad avviare un flusso di lavoro tramite eventi GitHub come push e pull-request, è possibile eseguire un flusso di lavoro in base a una pianificazione o dopo un evento esterno a GitHub.

È possibile che un flusso di lavoro venga eseguito solo dopo che un utente ha completato un'azione specifica, ad esempio dopo che un revisore approva una richiesta pull. Per questo scenario, è possibile attivare pull-request-review.

Un'altra azione che è possibile eseguire consiste nell'aggiungere un'etichetta alla richiesta pull. In questo caso, si usa l'azione pullreminders/label-when-approved-action.

Per esempio:

    steps:
     - name: Label when approved
       uses: pullreminders/label-when-approved-action@main
       env:
         APPROVALS: "1"
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         ADD_LABEL: "approved"

env Nel blocco si impostano le variabili di ambiente per l'azione. Ad esempio, è possibile impostare il numero di responsabili approvazione necessari per eseguire il flusso di lavoro. In questo esempio è uno. La secrets.GITHUB_TOKEN variabile di autenticazione è necessaria perché l'azione deve apportare modifiche al repository aggiungendo un'etichetta. Immettere infine il nome dell'etichetta da aggiungere.

L'aggiunta di un'etichetta potrebbe essere un evento che avvia un altro flusso di lavoro, ad esempio un'unione. Questo evento viene illustrato nel modulo successivo, che descrive l'uso del recapito continuo in GitHub Actions.

Commenti e suggerimenti

Questa pagina è stata utile?