Personalizzare il flusso di lavoro con le variabili di ambiente

  • 8 minuti

In questa unità si apprenderà come configurare e gestire un comportamento specifico dell'ambiente usando variabili, contesti e script personalizzati nei flussi di lavoro di GitHub Actions.

Per implementare questo processo, si apprenderà come:

  • Usare le variabili di ambiente predefinite e personalizzate.
  • Accedere alle informazioni contestuali nei flussi di lavoro.
  • Impostare le variabili di ambiente in ambiti di flusso di lavoro diversi.
  • Usare script personalizzati con la parola chiave run.
  • Applicare le protezioni dell'ambiente per le distribuzioni.

Contesti e variabili di ambiente predefinite

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 distinguono maiuscole e minuscole e si riferiscono ai valori di configurazione per il sistema e per l'utente corrente. È consigliabile usare queste 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. Sebbene le variabili di ambiente predefinite possano essere usate solo all'interno dello strumento di esecuzione, è possibile usare le variabili di contesto in qualsiasi punto 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 la diramazione che ha attivato il flusso di lavoro. Se il ramo è main, il runner viene eseguito e stampa "Distribuzione sul server di produzione nel ramo $GITHUB_REF". La variabile $GITHUB_REF di ambiente predefinita viene usata nel runner per fare riferimento al ramo. Si noti che le variabili di ambiente predefinite sono tutte maiuscole laddove le variabili di contesto sono tutte minuscole.

Informazioni contestuali disponibili in un flusso di lavoro

Utilizzare i contesti per accedere alle informazioni sulle esecuzioni dei flussi di lavoro, le variabili, gli ambienti di esecuzione, i processi e le fasi. Ogni contesto è un oggetto che contiene proprietà che possono essere altri oggetti o stringhe. I contesti disponibili includono github, env, vars, job, jobs, steps, runner, secrets, strategy, matrix, needs e inputs.

La tabella seguente elenca i contesti e le descrizioni del flusso di lavoro:

Contesto Descrizione
github Informazioni sull'esecuzione del flusso di lavoro. Per altre informazioni, vedere github contesto.
env Contiene le variabili impostate in un flusso di lavoro, un processo o un passaggio. Per altre informazioni, vedere env contesto.
vars Contiene le variabili impostate a livello di repository, organizzazione o ambiente. Per altre informazioni, vedere vars contesto.
job Informazioni sul processo in esecuzione. Per altre informazioni, vedere job contesto.
jobs Solo per i flussi di lavoro riutilizzabili, contiene gli output dei processi dal flusso di lavoro riutilizzabile. Per altre informazioni, vedere jobs contesto.
steps Informazioni sui passaggi eseguiti nell'attività attuale. Per altre informazioni, vedere steps contesto.
runner Informazioni sullo strumento di esecuzione che esegue il processo corrente. Per altre informazioni, vedere runner contesto.
secrets Contiene i nomi e i valori dei segreti disponibili per l'esecuzione di un workflow. Per altre informazioni, vedere secrets contesto.
strategy Informazioni sulla strategia di esecuzione della matrice per l'attività corrente. Per altre informazioni, vedere strategy contesto.
matrix Contiene le proprietà della matrice definite nel flusso di lavoro che si applicano al processo corrente. Per altre informazioni, vedere matrix contesto.
needs Contiene gli output di tutti i lavori definiti come dipendenza del lavoro corrente. Per altre informazioni, vedere needs contesto.
inputs Contiene gli input di un flusso di lavoro riutilizzabile o attivato manualmente. Per altre informazioni, vedere inputs contesto.

Diversi contesti sono disponibili in tempi differenti durante l'esecuzione di un flusso di lavoro. Ad esempio, è possibile usare il contesto secrets solo in punti specifici in un processo. Inoltre, è possibile usare alcune funzioni, ad esempio la hashFiles funzione, solo in posizioni specifiche.

Nella tabella seguente sono elencate le restrizioni per ogni contesto e funzione speciale in un flusso di lavoro. I contesti elencati sono disponibili solo per la chiave del flusso di lavoro indicata. Non è possibile usarli altrove. È possibile usare una funzione in qualsiasi punto, a meno che non sia elencata nella tabella seguente.

Chiave del flusso di lavoro Contesto Funzioni speciali
run-name github, inputs, vars Nessuno
concurrency github, inputs, vars Nessuno
env github, secrets, inputsvars Nessuno
jobs.<job_id>.concurrency github, needs, strategy, matrix, inputsvars Nessuno
jobs.<job_id>.container github, needs, strategy, matrix, varsinputs Nessuno
jobs.<job_id>.container.credentials github, needs, strategy, matrixenv, vars, , secretsinputs Nessuno
jobs.<job_id>.container.env.<env_id> github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs Nessuno
jobs.<job_id>.container.image github, needs, strategy, matrix, varsinputs Nessuno
jobs.<job_id>.continue-on-error github, needs, strategy, vars, matrixinputs Nessuno
jobs.<job_id>.defaults.run github, needs, strategy, matrixenv, , varsinputs Nessuno
jobs.<job_id>.env github, needs, strategy, matrixvars, , secretsinputs Nessuno
jobs.<job_id>.environment github, needs, strategy, matrix, varsinputs Nessuno
jobs.<job_id>.environment.url github, needs, strategy, matrix, job, runner, env, vars, steps, inputs Nessuno
jobs.<job_id>.if github, needs, varsinputs always, canceled, successfailure
jobs.<job_id>.name github, needs, strategy, matrix, varsinputs Nessuno
jobs.<job_id>.outputs.<output_id> github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs Nessuno
jobs.<job_id>.runs-on github, needs, strategy, matrix, varsinputs Nessuno
jobs.<job_id>.secrets.<secrets_id> github, needs, strategy, matrixsecrets, , inputsvars Nessuno
jobs.<job_id>.services github, needs, strategy, matrix, varsinputs Nessuno
jobs.<job_id>.services.<service_id>.credentials github, needs, strategy, matrixenv, vars, , secretsinputs Nessuno
jobs.<job_id>.services.<service_id>.env.<env_id> github, needs, strategy, matrix, job, runner, env, vars, secrets, inputs Nessuno
jobs.<job_id>.steps.continue-on-error github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.env github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.if github, needs, strategy, matrix, job, runner, env, vars, steps, inputs always, canceled, success, , failure, hashFiles
jobs.<job_id>.steps.name github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.run github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.timeout-minutes github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.with github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.steps.working-directory github, needs, strategy, matrix, job, runner, env, vars, secrets, steps, inputs hashFiles
jobs.<job_id>.strategy github, richiede, vars, inputs, Nessuno
jobs.<job_id>.timeout-minutes github, needs, strategy, matrix, varsinputs Nessuno
jobs.<job_id>.with.<with_id> github, needs, strategy, matrix, inputsvars Nessuno
on.workflow_call.inputs.<inputs_id>.default github, inputs, vars Nessuno
on.workflow_call.outputs.<output_id>.value github, lavori, vars, inputs Nessuno

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

Impostare variabili di ambiente personalizzate in un flusso di lavoro

È possibile definire le variabili di ambiente con ambito per l'intero flusso di lavoro usando env al livello superiore del file del flusso di lavoro. Definire l'ambito del contenuto di un processo all'interno di un flusso di lavoro usando jobs.<job_id>.env. È possibile definire l'ambito di una variabile di ambiente in un passaggio specifico all'interno di un processo usando jobs.<job_id>.steps[*].env.

Ecco un esempio che mostra tutti e tre gli scenari in un file del flusso di lavoro:

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Usare un contesto predefinito in un flusso di lavoro

La piattaforma GitHub imposta le variabili di ambiente predefinite. Non sono definiti in un flusso di lavoro, ma è possibile usare una variabile di ambiente predefinita in un flusso di lavoro nel contesto appropriato. La maggior parte di queste variabili, diversa da CI, inizia con GITHUB_* o RUNNER_*. Gli ultimi due tipi non possono essere sovrascritti. Inoltre, queste variabili predefinite hanno una proprietà di contesto corrispondente e denominata in modo analogo. Ad esempio, la RUNNER_* serie di variabili predefinite ha una proprietà di contesto corrispondente di runner.*.

Ecco un esempio di come accedere alle variabili predefinite in un flusso di lavoro applicando questi metodi:

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

Per altre informazioni, vedere Variabili di ambiente predefinite.

Passare variabili di ambiente personalizzate a un flusso di lavoro

È possibile passare variabili di ambiente personalizzate da un passaggio di un processo del flusso di lavoro ai passaggi successivi all'interno del processo. Generare un valore in un passaggio di un processo e assegnare il valore a una variabile di ambiente esistente o nuova. Successivamente, si scrive la coppia variabile/valore nel file di ambiente GITHUB_ENV. È possibile usare il file di ambiente in un'azione o a partire da un comando shell nel job del flusso di lavoro usando la parola chiave run.

Il passaggio che crea o aggiorna la variabile di ambiente non ha accesso al nuovo valore, ma tutti i passaggi successivi di un processo hanno accesso.

Ecco un esempio:

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

Aggiungere protezioni dell'ambiente

È possibile aggiungere regole di protezione per gli ambienti definiti per il repository GitHub.

Per aggiungere un ambiente al tuo repository, fai quanto segue:

  1. Seleziona Impostazioni.

    Barra dei menu di un'interfaccia Web con schede come Codice, Problemi e Wiki; Le impostazioni sono evidenziate.

  2. Nel riquadro sinistro selezionare Ambiente.

    Screenshot di un menu Impostazioni in Generale con sezioni per Accesso, Codice e automazione, Sicurezza e integrazioni. L'opzione Ambienti è evidenziata.

  3. Selezionare il pulsante Nuovo ambiente per aggiungere e configurare un ambiente e aggiungere protezioni.

    Screenshot della pagina Impostazioni repository GitHub che mostra la sezione Ambienti con un messaggio che indica che non esistono ambienti e il pulsante Nuovo ambiente evidenziato.

Informazioni sugli ambienti

Usare gli ambienti per descrivere una destinazione di distribuzione generale, ad esempio produzione, gestione temporanea o sviluppo. Quando un flusso di lavoro di GitHub Actions viene distribuito in un ambiente, l'ambiente viene visualizzato nella pagina principale del repository. È possibile usare gli ambienti per richiedere l'approvazione di un processo per continuare, limitare i rami che possono attivare un flusso di lavoro, controllare le distribuzioni usando regole di protezione della distribuzione personalizzate o limitare l'accesso ai segreti.

Ogni processo in un flusso di lavoro può fare riferimento a un ambiente. Tutte le regole di protezione impostate per l'ambiente devono passare prima che un processo che faccia riferimento all'ambiente venga inviato a uno strumento di esecuzione. Il processo può accedere ai segreti dell'ambiente solo dopo che è stato inviato a uno strumento di esecuzione.

Quando un flusso di lavoro fa riferimento a un ambiente, l'ambiente viene visualizzato nelle distribuzioni del repository.

Regole di protezione dell'ambiente

Le regole di protezione della distribuzione nell'ambiente richiedono che condizioni specifiche siano soddisfatte affinché un processo che fa riferimento all'ambiente proceda. È possibile usare le regole di protezione della distribuzione per richiedere un'approvazione manuale, ritardare un processo o limitare l'ambiente a rami specifici. È anche possibile creare e implementare regole di protezione personalizzate basate su GitHub Apps per usare i sistemi partner per controllare le distribuzioni che fanno riferimento agli ambienti configurati in GitHub.

Ecco una spiegazione di queste regole di protezione:

  • Regole di protezione dei revisori necessarie. Usare questa regola per richiedere a una persona o a un team specifico di approvare i processi del flusso di lavoro che fanno riferimento all'ambiente. È possibile elencare fino a sei utenti o team come revisori. I revisori devono disporre almeno delle autorizzazioni di lettura per il repository. Per procedere, è necessario che un solo revisore richiesto approvi il processo.

    È anche possibile impedire revisioni autonome per le distribuzioni in un ambiente protetto. Se si abilita questa impostazione, gli utenti che avviano una distribuzione non possono approvare il processo di distribuzione, anche se sono un revisore obbligatorio. Abilitando le autovalutazioni, si garantisce che più di una persona riveda le distribuzioni in ambienti protetti.

    Per maggiori informazioni sulla revisione delle attività che fanno riferimento a un ambiente con revisori richiesti, vedere Esaminare le implementazioni.

  • Regole di protezione timer di attesa. È possibile usare una regola di protezione timer di attesa per ritardare un processo per un periodo di tempo specifico dopo l'attivazione iniziale del processo, prima che la distribuzione nell'ambiente proceda. L'ora (in minuti) deve essere un numero intero compreso tra 1 e 43.200 (30 giorni). Il tempo di attesa non viene conteggiato per il tempo fatturabile.

  • Regole di protezione di diramazioni e tag. È possibile usare le regole di protezione dei tag e dei rami di distribuzione per limitare i rami e i tag usati per la distribuzione nell'ambiente. Sono disponibili diverse opzioni per il ramo di distribuzione e le regole di protezione dei tag per un ambiente.

    • Nessuna restrizione non imposta alcuna restrizione per la diramazione o il tag che può essere distribuito nell'ambiente.
    • Solo rami protetti consente la distribuzione nell'ambiente esclusivamente di rami con regole di protezione abilitate. Se non sono definite regole di protezione dei rami per qualsiasi ramo nel repository, tutti i rami possono essere distribuiti. L'impostazione Rami e tag selezionati garantisce che solo rami e tag corrispondenti ai modelli di nome specificati possano essere distribuiti nell'ambiente.
    • Se si specifica releases/* come ramo di distribuzione o regola tag, solo un ramo o un tag con un nome che inizia con releases/ può essere distribuito nell'ambiente. (I caratteri jolly non corrispondono a /. Per la corrispondenza di diramazioni o tag che iniziano con release/ e contengono un'altra barra singola, usare release/*/*.) Se si aggiunge main come regola di diramazione, nell'ambiente può essere distribuita anche una diramazione denominata main.

  • Regole di protezione personalizzate della distribuzione. È possibile creare regole di protezione personalizzate per limitare le distribuzioni e usare servizi partner. Ad esempio, è possibile usare sistemi di osservabilità, sistemi di gestione delle modifiche, sistemi di qualità del codice o altre configurazioni manuali usate per valutare la conformità e fornire approvazioni automatiche per le distribuzioni in GitHub.

    Dopo aver creato regole di protezione della distribuzione personalizzate e installarle in un repository, è possibile abilitare la regola di protezione della distribuzione personalizzata per qualsiasi ambiente nel repository.

    Screenshot che mostra la pagina Impostazioni per la configurazione di Environment1 con opzioni per revisori, timer di attesa, regole personalizzate e restrizioni di ramo.

Annotazioni

Se si dispone di un piano GitHub Free, GitHub Pro o GitHub Team, le regole di proiezione della distribuzione dell'ambiente sono disponibili solo per i repository pubblici; ad eccezione delle regole di protezione di rami e tag. Per gli utenti che hanno piani GitHub Pro o GitHub Team, le regole di protezione dei rami e dei tag sono disponibili anche per i repository privati.

Script nel flusso di lavoro

Negli esempi di frammenti di codice del flusso di lavoro precedente, viene usata la parola chiave run per generare una stringa di testo. Poiché la parola chiave run indica al processo di 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