Variables

À propos des variables

Vous pouvez utiliser des variables pour stocker les informations que vous souhaitez référencer dans votre workflow. Vous référencez des variables au sein d’une étape de workflow ou d’une action, et les variables sont interpolées sur la machine d’exécuteur qui exécute votre workflow. Les commandes qui s’exécutent dans des actions ou des étapes de workflow peuvent créer, lire ou modifier des variables.

Vous pouvez définir vos propres variables personnalisées, vous pouvez utiliser les variables par défaut que GitHub définit automatiquement, et vous pouvez également utiliser toutes les autres variables définies dans l’environnement de travail sur l’exécuteur. Les variables respectent la casse.

Définition de variables d’environnement

Pour définir une variable d’environnement personnalisée, vous pouvez la définir à l’aide de la clé env dans le fichier de workflow. L’étendue d’une variable personnalisée définie par cette méthode est limitée à l’élément dans lequel elle est définie. Vous pouvez définir des variables dont l’étendue est :

• Le workflow entier, en utilisant env au niveau supérieur du fichier de workflow.
• Le contenu d’un travail au sein d’un workflow, en utilisant jobs.<job_id>.env.
• Une étape spécifique dans un travail, en utilisant jobs.<job_id>.steps[*].env.

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

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

Vous pouvez accéder aux valeurs de variable env à l’aide de variables d’environnement d’exécuteur ou de contextes. L’exemple ci-dessus montre trois variables personnalisées utilisées en tant que variables d’environnement dans une commande echo : $DAY_OF_WEEK, $Greeting et $First_Name. Les valeurs de ces variables sont définies et limitées respectivement au niveau du workflow, du travail et de l’étape. Pour plus d’informations sur l’accès aux valeurs de variable à l’aide de contextes, consultez « Utilisation de contextes pour accéder aux valeurs de variable ».

Étant donné que l’interpolation des variables d’environnement d’exécuteur est effectuée une fois qu’un travail de workflow est envoyé à une machine d’exécuteur, vous devez utiliser la syntaxe appropriée pour l’interpréteur de commandes utilisé sur l’exécuteur. Dans cet exemple, le workflow spécifie ubuntu-latest. Par défaut, les exécuteurs Linux utilisent l’interpréteur de commandes bash. Vous devez donc utiliser la syntaxe $NAME. Si le workflow a spécifié un exécuteur Windows, vous utiliserez la syntaxe pour PowerShell, $env:NAME. Pour plus d’informations sur les interpréteurs de commandes, consultez « Workflow syntax for GitHub Actions ».

Conventions d’affectation de noms pour les variables d’environnement

Lorsque vous définissez une variable d’environnement, vous ne pouvez pas utiliser les noms de variable d’environnement par défaut. Pour obtenir la liste complète des variables d’environnement par défaut, consultez « Variables d’environnement par défaut » ci-dessous. Si vous tentez de remplacer la valeur de l’une de ces variables par défaut, l’affectation est ignorée.

Toutes les nouvelles variables que vous définissez et qui pointent vers un emplacement dans le système de fichiers doivent avoir un suffixe _PATH. Les variables par défaut GITHUB_ENV et GITHUB_WORKSPACE sont des exceptions à cette convention.

Utilisation de contextes pour accéder aux valeurs des variables

Les contextes offrent un moyen d’accéder aux informations sur les exécutions de workflow, les variables, les environnements d’exécuteur, les travaux et les étapes. Pour plus d’informations, consultez « Contextes ». Il existe de nombreux autres contextes que vous pouvez utiliser à diverses fins dans vos workflows. Pour plus d’informations sur l’emplacement où vous pouvez utiliser des contextes spécifiques au sein d’un workflow, consultez « Contextes ».

Vous pouvez accéder aux valeurs des variables d’environnement à l’aide du contexte env.

Utilisation du contexte env pour accéder aux valeurs des variables d’environnement

Outre les variables d’environnement d’exécuteur, GitHub Actions vous permet de définir et de lire des valeurs de clés env à l’aide de contextes. Les variables d’environnement et les contextes sont destinés à être utilisés à différents points du workflow.

Les variables d’environnement d’exécuteur sont toujours interpolées sur la machine d’exécuteur. Toutefois, les parties d’un workflow sont traitées par GitHub Actions et ne sont pas envoyées à l’exécuteur. Vous ne pouvez pas utiliser de variables d’environnement dans ces parties d’un fichier de workflow. À la place, vous pouvez utiliser des contextes. Par exemple, une condition if, qui détermine si un travail ou une étape sont envoyés à l’exécuteur, est toujours traitée par GitHub Actions. Vous pouvez utiliser un contexte dans une instruction conditionnelle if pour accéder à la valeur d’une variable.

env:
  DAY_OF_WEEK: Monday

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

env:
  DAY_OF_WEEK: Monday

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

Dans cette modification de l’exemple précédent, nous avons introduit une condition if. L’étape de workflow est désormais exécutée uniquement si la variable DAY_OF_WEEK a pour valeur « Monday » (Lundi). Nous accédons à cette valeur à partir de l’instruction conditionnelle if en utilisant le contexte env.

Vous utilisez généralement le contexte env ou github pour accéder aux valeurs des variables figurant dans les parties du workflow traitées avant que les travaux soient envoyés aux exécuteurs.

Variables d’environnement par défaut

Les variables d’environnement par défaut que GitHub définit sont disponibles pour chaque étape d’un workflow.

Étant donné que les variables d’environnement par défaut sont définies par GitHub et non dans un flux de travail, elles ne sont pas accessibles via le contexte env. Cependant, la plupart des variables par défaut ont une propriété de contexte correspondante et portant un nom similaire. Par exemple, la valeur de la variable GITHUB_REF peut être lue pendant le traitement du workflow à l’aide de la propriété de contexte ${{ github.ref }}.

Vous ne pouvez pas remplacer la valeur des variables d’environnement par défaut appelées GITHUB_* et RUNNER_*. Actuellement, vous pouvez remplacer la valeur de la variable CI. Toutefois, il n’est pas garanti que cela sera toujours possible. Pour plus d’informations sur la définition des variables d’environnement, consultez « Définition des variables d’environnement pour un seul flux de travail » et « Workflow commands for GitHub Actions ».

Nous recommandons vivement que les actions utilisent des variables pour accéder au système de fichiers plutôt que des chemins de fichier codés en dur. GitHub définit les variables pour les actions à utiliser dans tous les environnements d’exécution.

Détection du système d’exploitation

Vous pouvez écrire un fichier de workflow individuel qui peut être utilisé pour différents systèmes d’exploitation à l’aide de la variable d’environnement par défaut RUNNER_OS et de la propriété de contexte correspondante ${{ runner.os }}. Par exemple, le workflow suivant peut être exécuté correctement si vous avez remplacé le système d’exploitation macos-latest par windows-latest sans avoir à modifier la syntaxe des variables d’environnement, ce qui diffère selon l’interpréteur de commandes utilisé par l’exécuteur.

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."

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."

Dans cet exemple, les deux instructions if vérifient la propriété os du contexte runner pour déterminer le système d’exploitation de l’exécuteur. Les conditions if sont traitées par GitHub Actions et seules les étapes où la vérification est résolue comme true sont envoyées à l’exécuteur. Ici, l’une des vérifications sera toujours true et l’autre false, si bien qu’une seule de ces étapes est envoyée à l’exécuteur. Une fois le travail envoyé à l’exécuteur, l’étape est exécutée et la variable d’environnement dans la commande echo est interpolée à l’aide de la syntaxe appropriée ($env:NAME pour PowerShell sur Windows, et $NAME pour bash et sh sur Linux et MacOS). Dans cet exemple, l’instruction runs-on: macos-latest signifie que la deuxième étape sera exécutée.

Transmission de valeurs entre les étapes et les travaux dans un workflow

Si vous générez une valeur dans une étape d’un travail, vous pouvez utiliser cette valeur dans les étapes suivantes du même travail en affectant la valeur à une variable d’environnement existante ou nouvelle, puis en écrivant cette dernière dans le fichier d’environnement GITHUB_ENV. Le fichier d’environnement peut être utilisé directement par une action ou à partir d’une commande shell dans le fichier de workflow à l’aide du mot clé run. Pour plus d’informations, consultez « Workflow commands for GitHub Actions ».

Si vous souhaitez transmettre une valeur d’une étape d’un travail dans un workflow vers une étape d’un autre travail dans le workflow, vous pouvez définir la valeur en tant que sortie de travail. Vous pouvez ensuite référencer cette sortie de travail à partir d’une étape dans un autre travail. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».