Explorer des contextes et des expressions dans GitHub

  • 10 minutes

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. Chaque contexte est un objet qui contient des propriétés, qui peuvent être des chaînes ou d’autres objets.

Vous pouvez accéder aux contextes à l’aide de la syntaxe d’expression. Une expression peut être une combinaison quelconque de valeurs littérales, de références à un contexte ou de fonctions. Vous pouvez combiner des littéraux, des références de contexte et des fonctions en utilisant des opérateurs.

Contextes

Lors de la création de flux de travail et d’actions, vous devez toujours déterminer si votre code pourrait exécuter des entrées non fiables provenant de personnes malveillantes potentielles. Certains contextes doivent être traités comme des entrées non fiables, car un attaquant peut insérer son propre contenu malveillant. Pour plus d’informations, consultez Renforcement de la sécurité pour GitHub Actions. »

Le tableau suivant contient des exemples de contextes disponibles dans GitHub, ce n’est pas une liste complète.

Nom du contexte Type Description
github object Informations sur l’exécution du workflow.
env object Contient des variables définies dans un workflow, un travail ou une étape.
vars object Contient des variables définies au niveau du référentiel, de l'organisation ou de l'environnement.
job object Informations sur le travail en cours d’exécution.

Conseil / Astuce

Pour obtenir une liste complète des contextes, consultez À propos des contextes.

Déterminer quand utiliser des contextes

GitHub Actions inclut deux collections de variables appelées variables par défaut et contextes. Ces variables sont destinées à être utilisées à différents stades du workflow.

  • Variables d’environnement par défaut : ces variables d’environnement existent uniquement sur l’exécuteur qui exécute votre travail.
  • Contextes : vous pouvez utiliser la plupart des contextes à tout moment dans votre flux de travail, notamment lorsque les variables par défaut ne sont pas disponibles.

Dans l’exemple suivant, l’instruction if vérifie le github.ref contexte pour déterminer le nom de la branche actuelle. La vérification d’if est traitée et le travail est envoyé à l’exécuteur uniquement si le résultat est true. Une fois le travail envoyé à l’exécuteur, l’étape est exécutée et fait référence à la $GITHUB_REF variable de l’exécuteur.

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"

Contextes disponibles dans GitHub Actions

Le tableau suivant contient les contextes de niveau supérieur disponibles, une brève description et un lien vers plus d’informations sur les propriétés de l’objet.

Contexte de niveau supérieur Description Propriétés et exemples
github Contexte de niveau supérieur disponible pendant tout travail ou étape d’un workflow. Propriétés du github contexte.
env Contient des variables définies dans un workflow, un travail ou une étape. Il ne contient pas de variables héritées par le processus de l’exécuteur. Propriétés du env contexte.
vars Contient des variables de configuration personnalisées définies au niveau de l’organisation, du référentiel et de l’environnement. Exemples d’utilisation vars .
job Contient des informations sur le travail en cours d’exécution. Propriétés du job contexte.
jobs Disponible uniquement dans les flux de travail réutilisables et ne peut être utilisé que pour définir des sorties pour un flux de travail réutilisable. Propriétés du jobs contexte.
steps Contient des informations sur les étapes terminées dans le travail actuel pour lesquelles une valeur id est spécifiée. Propriétés du steps contexte.
runner Contient des informations sur l’exécuteur qui exécute le travail en cours. Propriétés du runner contexte.
secrets Contient les noms et valeurs des secrets disponibles pour une exécution de workflow. Propriétés du secrets contexte.
strategy Contient des informations sur la stratégie d’exécution de la matrice pour le travail actuel. Propriétés du strategy contexte.
matrix Contient les propriétés de matrice définies dans le fichier de flux de travail qui s’appliquent au travail actuel. Propriétés du matrix contexte.
needs Contient les sorties de toutes les tâches définies comme dépendant directement de la tâche actuelle. Propriétés du matrix contexte.
inputs Contient les propriétés d’entrée passées à une action, à un flux de travail réutilisable ou à un flux de travail déclenché manuellement. Propriétés du inputs contexte.

Expressions

Vous pouvez utiliser des expressions pour définir par programmation des variables d’environnement dans les fichiers de workflow et les contextes d’accès. Une expression peut être une combinaison quelconque de valeurs littérales, de références à un contexte ou de fonctions. Vous pouvez combiner des littéraux, des références de contexte et des fonctions en utilisant des opérateurs.

Les expressions sont couramment utilisées avec le mot clé conditionnel if dans un fichier de workflow pour déterminer si une étape doit être exécutée ou non. Lorsqu'une if condition est true remplie, l'étape s'exécute.

Vous devez utiliser une syntaxe spécifique, ${{ <expression> }}pour indiquer à GitHub d’évaluer une expression plutôt que de la traiter comme une chaîne. L’exception à cette règle est lorsque vous utilisez des expressions dans une if clause, où elles peuvent généralement être omises ${{ et }}.

L’exemple de code suivant montre la définition d’une variable d’environnement.

env:
  MY_ENV_VAR: ${{ <expression> }}

Littéraux

Dans le cadre d’une expression, vous pouvez utiliser des types de données boolean, null, number ou string. Dans les conditionnels, les valeurs falsy (false, 0, -0, "", '', null) sont converties en false, et les valeurs truthy (true et d'autres valeurs non falsy) sont converties en true. Voici des exemples d’implémentation de littéraux.

env:
  myNull: ${{ null }}
  myBoolean: ${{ false }}
  myIntegerNumber: ${{ 711 }}
  myFloatNumber: ${{ -9.2 }}
  myHexNumber: ${{ 0xff }}
  myExponentialNumber: ${{ -2.99e-2 }}
  myString: Mona the Octocat
  myStringInBraces: ${{ 'It''s open source!' }}

Opérateurs

Les opérateurs jouent un rôle crucial dans l’évaluation des expressions. Une expression peut se composer de valeurs littérales, de références à des contextes ou de fonctions. Les opérateurs vous permettent de combiner ces éléments pour créer des expressions plus complexes. Voici quelques opérateurs clés :

  • Opérateurs logiques :

    • && (et) : combine deux conditions, dont les deux doivent être vraies pour que l’expression globale soit évaluée comme true.
    • || (ou) : combine deux conditions et l’expression prend la valeur true si l’une ou l’autre condition est vraie.
    • ! (pas): Inverse une condition, inversant sa valeur de vérité.

  • Opérateurs d’égalité :

    • == (égal) : compare deux valeurs pour l’égalité.
    • != (pas égal) : vérifie si deux valeurs ne sont pas égales.

  • Opérateurs de comparaison :

    • < (inférieur à)
    • > (supérieur à)
    • <= (inférieur ou égal à)
    • >= (supérieur ou égal à)

Ces opérateurs vous permettent de créer des flux de travail dynamiques en déterminant quand des étapes spécifiques doivent s’exécuter en fonction des conditions. N’oubliez pas d’utiliser la syntaxe correcte pour les expressions, telles que $\{\{ <expression> \}\}$, pour garantir une évaluation appropriée.

Pour plus d’informations sur les opérateurs, consultez Opérateurs.