Expressions

À 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 conditionnels if, consultez « Workflow syntax for GitHub Actions ».

Exemple d’expression dans une condition if

steps:
  - uses: actions/hello-world-javascript-action@e76147da8e5c81eaf017dede5645551d4b94427b
    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ées	Valeur littérale
boolean	true ou false
null	null
number	Tout format de nombre pris en charge par JSON.
string	Vous 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 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

Opérateur	Description
( )	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 :

  Type	Résultats
  Null	0
  Booléen	true retourne 1 false retourne 0
  String	Analysé depuis n’importe quel format de nombre JSON légal ; sinon NaN. Remarque : une chaîne vide retourne 0.
  Array	NaN
  Object	NaN

• 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 :

Type	Résultats
Null	''
Booléen	'true' ou 'false'
Nombre	Format décimal, exponentiel pour de grands nombres
Array	Les tableaux ne sont pas convertis en chaîne
Object	Les 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 de startsWith

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 de endsWith

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 de format

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 de join

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 de toJSON

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 "::set-output name=matrix::{\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}"
  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 « Workflow syntax for 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 « Workflow syntax for GitHub Actions » et « Metadata syntax for GitHub Actions ».

success

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

Exemple de success

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. L’expression always est à utiliser de préférence au niveau de l’étape ou sur des tâches que vous prévoyez d’exécuter même quand un travail est annulé. Par exemple, vous pouvez utiliser always pour envoyer des journaux même quand un travail est annulé.

Exemple de always

if: ${{ always() }}

annulé

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

Exemple de cancelled

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 de failure

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 de failure avec des conditions

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.