Personalizzare il flusso di lavoro con variabili di ambiente e dati dell'artefatto

  • 12 minuti

Qui verrà illustrato come usare le variabili di ambiente predefinite e personalizzate, gli script personalizzati, come memorizzare le dipendenze nella cache e passare i dati degli artefatti tra i processi. Viene descritto anche come accedere ai log del flusso di lavoro sia dal sito Web di GitHub che dagli endpoint dell'API REST.

Variabili di ambiente predefinite e contesti

All'interno del flusso di lavoro di GitHub Actions sono disponibili diverse variabili di ambiente predefinite che è possibile usare, ma solo all'interno dello strumento di esecuzione che esegue un processo. Queste variabili predefinite fanno distinzione tra maiuscole e minuscole e fanno riferimento ai valori di configurazione per il sistema e per l'utente corrente. È consigliabile usare le variabili di ambiente predefinite per fare riferimento al file system anziché usare percorsi di file hardcoded. Per usare una variabile di ambiente predefinita, specificare $ seguito dal nome della variabile di ambiente.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Oltre alle variabili di ambiente predefinite, è possibile usare variabili definite come contesti. I contesti e le variabili predefinite sono simili in quanto entrambi consentono di accedere alle informazioni sull'ambiente, ma presentano differenze importanti. Mentre le variabili di ambiente predefinite possono essere usate solo all'interno dello strumento di esecuzione, le variabili di contesto possono essere usate in qualsiasi punto all'interno del flusso di lavoro. Ad esempio, le variabili di contesto consentono di eseguire un'istruzione if per valutare un'espressione prima che lo strumento di esecuzione venga eseguito.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Questo esempio usa il contesto github.ref per controllare il ramo che ha attivato il flusso di lavoro. Se il ramo è main, lo strumento di esecuzione viene eseguito e genera il messaggio "Deploying to production server on branch $GITHUB_REF" (Distribuzione nel server di produzione sul ramo $GITHUB_REF). La variabile di ambiente predefinita $GITHUB_REF viene usata nello strumento di esecuzione per fare riferimento al ramo. Si noti che le variabili di ambiente predefinite sono tutte maiuscole laddove le variabili di contesto sono tutte minuscole.

Variabili di ambiente personalizzate

Analogamente all'uso delle variabili di ambiente predefinite, è possibile usare variabili di ambiente personalizzate nel file del flusso di lavoro. Per creare una variabile personalizzata, è necessario definirla nel file del flusso di lavoro usando il contesto env. Se si vuole usare il valore di una variabile di ambiente all'interno di uno strumento di esecuzione, è possibile usare il normale metodo del sistema operativo dello strumento di esecuzione per leggere le variabili di ambiente.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

Script nel flusso di lavoro

Negli esempi di frammenti di codice del flusso di lavoro precedente la parola chiave run viene usata semplicemente per generare una stringa di testo. Poiché la parola chiave run indica al processo per eseguire un comando nello strumento di esecuzione, si usa la parola chiave run per eseguire azioni o script.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

In questo esempio si usa npm per installare il bats pacchetto di test software usando la run parola chiave . È anche possibile eseguire uno script come azione. È possibile archiviare lo script nel repository, spesso in una directory .github/scripts/, e quindi specificare il percorso e il tipo di shell usando la parola chiave run.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash

Memorizzare le dipendenze nella cache con l'azione di memorizzazione nella cache

Quando si compila un flusso di lavoro, spesso è necessario riutilizzare gli stessi output o scaricare le dipendenze da un'esecuzione a un'altra. Invece di scaricare queste dipendenze più volte, è possibile memorizzarle nella cache per velocizzare e rendere più efficiente l'esecuzione del flusso di lavoro. Ciò può ridurre notevolmente il tempo necessario per eseguire determinati passaggi in un flusso di lavoro, perché i processi negli strumenti di esecuzione ospitati in GitHub vengono avviati ogni volta in un ambiente virtuale pulito. La memorizzazione nella cache delle dipendenze consente di ridurre il tempo necessario per ricreare i file di queste dipendenze.

Per memorizzare nella cache le dipendenze per un processo, usare l'azione di cache GitHub. Questa azione recupera una cache identificata da una chiave univoca specificata dall'utente. Quando l'azione trova la cache, recupera i file memorizzati nella cache del percorso configurato. Per usare l'azione cache , è necessario impostare alcuni parametri specifici:

Parametro Descrizione Richiesto
Key Fa riferimento all'identificatore della chiave creato durante il salvataggio e la ricerca di una cache. Sì
Percorso Fa riferimento al percorso del file nello strumento di esecuzione da memorizzare nella cache o da cercare. Sì
Chiavi di ripristino Sono costituite da chiavi esistenti alternative alle cache se la chiave della cache desiderata non viene trovata. No 
steps:
  - uses: actions/checkout@v2

  - name: Cache NPM dependencies
    uses: actions/cache@v2
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-cache-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-cache-

Nell'esempio precedente path è impostato su ~/.npm e key include il sistema operativo dello strumento di esecuzione e l'hash SHA-256 del file package-lock.json. L'aggiunta di un prefisso alla chiave con un ID, npm-cache in questo esempio, è utile quando si usa il fallback restore-keys e si hanno più cache.

Passare i dati dell'artefatto tra i processi

Analogamente al concetto di memorizzazione nella cache delle dipendenze all'interno del flusso di lavoro, è possibile passare i dati tra i processi all'interno dello stesso flusso di lavoro. È possibile eseguire questa operazione usando le azioni upload-artifact e download-artifact. I processi dipendenti dagli artefatti di un processo precedente devono attendere il completamento corretto del processo precedente prima di poter essere eseguiti. Ciò è utile se si dispone di una serie di processi che devono essere eseguiti in sequenza in base agli artefatti caricati da un processo precedente. Ad esempio, per job_2 è necessario job_1 con la sintassi needs: job_1.

name: Share data between jobs
on: push
jobs:
  job_1:
    name: Upload File
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello World" > file.txt
      - uses: actions/upload-artifact@v2
        with:
          name: file
          path: file.txt

  job_2:
    name: Download File
    runs-on: ubuntu-latest
    needs: job_1
    steps:
      - uses: actions/download-artifact@v2
        with:
          name: file
      - run: cat file.txt

L'esempio precedente include due processi. job_1 scrive il testo nel file file.txt e quindi usa l'azione actions/upload-artifact@v2 per caricare l'artefatto e archiviare i dati per un uso futuro all'interno del flusso di lavoro. job_2 richiede il completamento di job_1 con la sintassi needs: job_1 e quindi usa l'azione actions/download-artifact@v2 per scaricare l'artefatto e generare il contenuto di file.txt.

Abilitare la registrazione del debug del passaggio in un flusso di lavoro

In alcuni casi, i log del flusso di lavoro predefiniti non contengono dettagli sufficienti per diagnosticare il motivo per cui un'esecuzione, un processo o un passaggio di un flusso di lavoro specifico ha avuto esito negativo. In queste situazioni, è possibile abilitare una registrazione del debug aggiuntiva per due opzioni: esecuzioni e passaggi. Abilitare questa registrazione diagnostica impostando due segreti del repository che richiedono admin l'accesso al repository a true:

  • Per abilitare la registrazione diagnostica dello strumento di esecuzione, impostare il segreto ACTIONS_RUNNER_DEBUG nel repository che contiene il flusso di lavoro su true.
  • Per abilitare la registrazione diagnostica del passaggio, impostare il segreto ACTIONS_STEP_DEBUG nel repository che contiene il flusso di lavoro su true.

Accedere ai log del flusso di lavoro dall'interfaccia utente

Quando si pensa a una corretta automazione, si pensa di dedicare meno tempo possibile alla ricerca degli elementi che sono stati automatizzati, in modo da poter concentrare l'attenzione sugli aspetti importanti. A volte, tuttavia, le cose non vanno come previsto ed è necessario verificare gli eventi. Il processo di debug può essere frustrante, ma GitHub offre una struttura di layout chiara che consente di spostarsi rapidamente tra i processi mantenendo il contesto del passaggio di debug corrente. Per visualizzare i log di un flusso di lavoro eseguito in GitHub, è possibile seguire questa procedura:

  1. Passare alla scheda Azioni nel repository.
  2. Nella barra laterale sinistra fare clic sul flusso di lavoro desiderato.
  3. Nell'elenco delle esecuzioni del flusso di lavoro selezionare l'esecuzione desiderata.
  4. In Processiselezionare il processo desiderato.
  5. Leggere l'output del log.

Se all'interno di un flusso di lavoro ci sono più esecuzioni, è anche possibile selezionare il filtro Stato dopo aver scelto il flusso di lavoro e impostarlo su Errore per visualizzare solo le esecuzioni non riuscite all'interno del flusso di lavoro.

Accedere ai log del flusso di lavoro dall'API REST

Oltre a visualizzare i log con GitHub, è anche possibile usare l'API REST di GitHub per visualizzare i log per le esecuzioni del flusso di lavoro, eseguire di nuovo i flussi di lavoro o persino annullarne le esecuzioni. Per visualizzare il log di esecuzione di un flusso di lavoro con l'API, è necessario inviare una richiesta GET all'endpoint dei log. Tenere presente che chiunque abbia accesso in lettura al repository può usare questo endpoint. Se il repository è privato, è necessario usare un token di accesso con l'ambito repo.

Ad esempio, una richiesta GET per visualizzare il log di esecuzione di un flusso di lavoro specifico segue il percorso seguente:

GET /repos/{owner}/{repo}/actions/runs/{run_id}/logs