Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.

Expressions

Vous pouvez évaluer des expressions dans les workflows et les actions.

À propos des 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 à l’aide d’opérateurs. Pour plus d’informations sur les contextes, consultez « Contextes ».

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. Quand une condition if est true, l’étape s’exécute.

Vous devez utiliser une syntaxe spécifique pour indiquer à GitHub d’évaluer une expression plutôt que de la traiter comme une chaîne.

${{ <expression> }}

Quand vous utilisez des expressions dans un if conditionnel, vous pouvez omettre la syntaxe de l’expression (${{ }}), car GitHub évalue automatiquement le if conditionnel en tant qu’expression. Pour plus d’informations sur les conditions if, consultez « Syntaxe de workflow pour GitHub Actions ».

Avertissement : Au moment de la création de workflows et d’actions, vous devez toujours déterminer si votre code peut exécuter une entrée non fiable provenant d’attaquants potentiels. 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 « Présentation du risque d’injections de scripts ».

Exemple d’expression dans une condition if

steps:
  - uses: actions/hello-world-javascript-action@v1.1
    if: ${{ <expression> }}

Exemple de 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.

Type de donnéesValeur littérale
booleantrue ou false
nullnull
numberTout format de nombre pris en charge par JSON.
stringVous n’avez pas besoin de placer les chaînes entre ${{ et }}. Toutefois, si vous le faites, vous devez utiliser des guillemets simples (') autour de la chaîne. Pour utiliser un guillemet simple littéral, échappez le guillemet simple littéral en utilisant un guillemet simple supplémentaire (''). L’utilisation de guillemets doubles (") génère une erreur.

Exemple

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

OpérateurDescription
( )Regroupement logique
[ ]Index
.Annulation de référence de propriété
!Not
<Inférieur à
<=Inférieur ou égal à
>Supérieur à
>=Supérieur ou égal à
==Égal à
!=Différent de
&&and
||ou

GitHub effectue des comparaisons d’égalité faible.

  • Si les types ne correspondent pas, GitHub impose un type numéral. GitHub convertit les types de données en nombre à l’aide des conversions suivantes :

    TypeRésultats
    Null0
    Booléentrue retourne 1
    false retourne 0
    StringAnalysé depuis n’importe quel format de nombre JSON légal ; sinon NaN.
    Remarque : une chaîne vide retourne 0.
    ArrayNaN
    ObjectNaN
  • Une comparaison entre un NaN et un autre NaN n’entraîne pas true. Pour plus d’informations, consultez les « documents Mozilla sur NaN ».

  • GitHub ignore la casse lors de la comparaison de chaînes.

  • Les objets et les tableaux sont considérés comme égaux uniquement lorsqu’ils sont une même instance.

Fonctions

GitHub offre un ensemble de fonctions intégrées que vous pouvez utiliser dans des expressions. Certaines fonctions convertissent les valeurs en chaîne pour effectuer des comparaisons. GitHub convertit les types de données en chaîne à l’aide des conversions suivantes :

TypeRésultats
Null''
Booléen'true' ou 'false'
NombreFormat décimal, exponentiel pour de grands nombres
ArrayLes tableaux ne sont pas convertis en chaîne
ObjectLes objets ne sont pas convertis en chaîne

contains

contains( search, item )

Retourne true si search contient item. Si search est un tableau, cette fonction retourne true si item est un élément dans le tableau. Si search est une chaîne, cette fonction retourne true si l’élément item est une sous-chaîne de search. Cette fonction ne respecte pas la casse. Convertit les valeurs en chaîne.

Exemple utilisant une chaîne

contains('Hello world', 'llo') retourne true.

Exemple utilisant un filtre d’objet

contains(github.event.issue.labels.*.name, 'bug') retourne true si le problème lié à l’événement a une étiquette « bug ».

Pour plus d’informations, consultez « Filtres d’objet  ».

Exemple mettant en correspondance un tableau de chaînes

Au lieu d’écrire github.event_name == "push" || github.event_name == "pull_request", vous pouvez utiliser contains() avec fromJSON() pour vérifier si un tableau de chaînes contient un item.

Par exemple, contains(fromJSON('["push", "pull_request"]'), github.event_name) retourne true si github.event_name est « push » ou « pull_request ».

startsWith

startsWith( searchString, searchValue )

Retourne true quand searchString commence par searchValue. Cette fonction ne respecte pas la casse. Convertit les valeurs en chaîne.

Exemple

startsWith('Hello world', 'He') retourne true.

endsWith

endsWith( searchString, searchValue )

Retourne true si searchString se termine par searchValue. Cette fonction ne respecte pas la casse. Convertit les valeurs en chaîne.

Exemple

endsWith('Hello world', 'ld') retourne true.

format

format( string, replaceValue0, replaceValue1, ..., replaceValueN)

Remplace les valeurs dans la chaîne string, par la variable replaceValueN. Les variables dans la chaîne string sont spécifiées à l’aide de la syntaxe {N}, où N est un entier. Vous devez spécifier au moins une valeur replaceValue et une chaîne string. Il n’existe pas de maximum pour le nombre de variables (replaceValueN) utilisables. Échappez les accolades à l’aide d’accolades doubles.

Exemple

format('Hello {0} {1} {2}', 'Mona', 'the', 'Octocat')

Retourne « Hello Mona the Octocat ».

Exemple d’échappement d’accolades

format('{{Hello {0} {1} {2}!}}', 'Mona', 'the', 'Octocat')

Retourne « {Hello Mona the Octocat!} ».

join

join( array, optionalSeparator )

La valeur pour array peut être un tableau ou une chaîne. Toutes les valeurs contenues dans array sont concaténées en une chaîne. Si vous fournissez optionalSeparator, il est inséré entre les valeurs concaténées. Sinon, le séparateur par défaut , est utilisé. Convertit les valeurs en chaîne.

Exemple

join(github.event.issue.labels.*.name, ', ') peut retourner « bug, help wanted »

toJSON

toJSON(value)

Retourne une représentation JSON d’impression formatée de value. Vous pouvez utiliser cette fonction pour déboguer les informations fournies dans les contextes.

Exemple

toJSON(job) peut retourner { "status": "Success" }

fromJSON

fromJSON(value)

Retourne un objet JSON ou un type de données JSON pour value. Vous pouvez utiliser cette fonction pour fournir un objet JSON en tant qu’expression évaluée ou pour convertir des variables d’environnement à partir d’une chaîne.

Exemple de retour d’un objet JSON

Ce workflow définit une matrice JSON dans un travail et le transmet au travail suivant à l’aide d’une sortie et de fromJSON.

name: build
on: push
jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix={\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}" >> $GITHUB_OUTPUT
  job2:
    needs: job1
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.job1.outputs.matrix) }}
    steps:
      - run: build

Exemple retournant un type de données JSON

Ce workflow utilise fromJSON pour convertir les variables d’environnement d’une chaîne en booléen ou entier.

name: print
on: push
env:
  continue: true
  time: 3
jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
      - continue-on-error: ${{ fromJSON(env.continue) }}
        timeout-minutes: ${{ fromJSON(env.time) }}
        run: echo ...

hashFiles

hashFiles(path)

Retourne un hachage unique pour l’ensemble des fichiers qui correspondent au modèle path. Vous pouvez fournir un modèle path unique ou plusieurs modèles path séparés par des virgules. L’élément path est relatif au répertoire GITHUB_WORKSPACE et ne peut inclure que des fichiers à l’intérieur de GITHUB_WORKSPACE. Cette fonction calcule un hachage SHA-256 individuel pour chaque fichier correspondant, puis utilise ces hachages pour calculer un hachage SHA-256 final pour l’ensemble de fichiers. Si le modèle path ne correspond à aucun fichier, une chaîne vide est retournée. Pour plus d’informations sur SHA-256, consultez « SHA-2 ».

Vous pouvez utiliser des caractères de correspondance de modèle pour mettre en correspondance des noms de fichiers. La correspondance de modèle n’est pas sensible à la casse sur Windows. Pour plus d’informations sur les caractères de correspondance de modèle pris en charge, consultez « Syntaxe de workflow pour GitHub Actions ».

Exemple avec un modèle unique

Correspond à n’importe quel fichier package-lock.json dans le dépôt.

hashFiles('**/package-lock.json')

Exemple avec plusieurs modèles

Crée un hachage pour n’importe quels fichiers package-lock.json et Gemfile.lock dans le dépôt.

hashFiles('**/package-lock.json', '**/Gemfile.lock')

Fonctions de vérification d’état

Vous pouvez utiliser les fonctions de vérification d’état suivantes en tant qu’expressions dans les conditions if. Une vérification d’état par défaut de success() est appliquée, sauf si vous incluez l’une de ces fonctions. Pour plus d’informations sur les conditions if, consultez « Syntaxe de workflow pour GitHub Actions» et « Syntaxe des métadonnées pour les actions composites GitHub».

success

Retourne true quand aucune des étapes précédentes n’a échoué ou n’a été annulée.

Exemple

steps:
  ...
  - name: The job has succeeded
    if: ${{ success() }}

toujours

Provoque l’exécution systématique de l’étape et retourne true, même lorsqu’elle est annulée. Un travail ou une étape ne s’exécute pas quand un échec critique empêche l’exécution de la tâche. Par exemple, si l’obtention des sources a échoué.

Exemple

if: ${{ always() }}

annulé

Retourne true si le workflow a été annulé.

Exemple

if: ${{ cancelled() }}

échec

Retourne true quand une étape précédente quelconque d’un travail échoue. Si vous avez une chaîne de travaux dépendants, failure() retourne true si un travail ancêtre quelconque échoue.

Exemple

steps:
  ...
  - name: The job has failed
    if: ${{ failure() }}

échec avec conditions

Vous pouvez inclure des conditions supplémentaires pour qu’une étape s’exécute après un échec. Toutefois, vous devez toujours inclure failure() pour remplacer la vérification d’état par défaut success(), qui s’applique automatiquement aux conditions if qui ne contiennent pas de fonction de vérification d’état.

Exemple
steps:
  ...
  - name: Failing step
    id: demo
    run: exit 1
  - name: The demo step has failed
    if: ${{ failure() && steps.demo.conclusion == 'failure' }}

Filtres d’objets

Vous pouvez utiliser la syntaxe * pour appliquer un filtre et sélectionner des éléments correspondants dans une collection.

Par exemple, considérez un tableau d’objets nommé fruits.

[
  { "name": "apple", "quantity": 1 },
  { "name": "orange", "quantity": 2 },
  { "name": "pear", "quantity": 1 }
]

Le filtre fruits.*.name retourne le tableau [ "apple", "orange", "pear" ].

Vous pouvez également utiliser la syntaxe * sur un objet. Par exemple, supposons que vous avez un objet nommé vegetables.


{
  "scallions":
  {
    "colors": ["green", "white", "red"],
    "ediblePortions": ["roots", "stalks"],
  },
  "beets":
  {
    "colors": ["purple", "red", "gold", "white", "pink"],
    "ediblePortions": ["roots", "stems", "leaves"],
  },
  "artichokes":
  {
    "colors": ["green", "purple", "red", "black"],
    "ediblePortions": ["hearts", "stems", "leaves"],
  },
}

Le filtre vegetables.*.ediblePortions peut donner pour résultats :


[
  ["roots", "stalks"],
  ["hearts", "stems", "leaves"],
  ["roots", "stems", "leaves"],
]

Comme les objets ne conservent pas l’ordre, l’ordre de la sortie ne peut pas être garanti.