Évaluer des expressions dans les workflows et les actions.

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

Notez que dans les conditions, les valeurs erronées (false, 0, -0, "", '', null) sont forcées vers false, et les valeurs vraies (true et d’autres valeurs non erronées) sont forcées vers true.

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

Remarque

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

          `steps.<step_id>.outputs.<output_name>` est évalué en tant que chaîne. Vous devez utiliser une syntaxe spécifique pour indiquer à GitHub d’évaluer une expression plutôt que de la traiter comme une chaîne. Pour plus d’informations, consultez [AUTOTITLE](/actions/learn-github-actions/contexts#steps-context).

Pour la comparaison numérique, la fonction fromJSON() peut être utilisée pour convertir une chaîne en nombre. Pour plus d’informations sur la fonction fromJSON(), consultez fromJSON.

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
Boolean
```
        `true`retourne`1` <br /> 
        `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 |
Quand NaN est l’un des opérandes d’une comparaison relationnelle (>, <, >=, <=), le résultat est toujours false. 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.

Type	Résultats
Null	`0`
Boolean

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	`''`
Boolean

          `'true'` ou `'false'` |

contient

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 n’importe quel type de données qui peut être représenté dans JSON ou JavaScript, comme des chaînes, des booléens, des valeurs null, des tableaux et des objets.

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.

YAML

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: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"

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: echo "Matrix - Project ${{ matrix.project }}, Config ${{ matrix.config }}"

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.

YAML

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

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

Le flux de travail utilise la fonction fromJSON() pour convertir la variable d’environnement continue d’une chaîne en valeur booléenne, ce qui lui permet de déterminer s’il faut continuer à l’erreur ou non. De même, il convertit la variable d’environnement time d’une chaîne en entier, en définissant le délai d’expiration du projet en minutes.

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 la section 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 pour hashFiles suit la correspondance de modèle global et est insensible à la casse sur Windows. Pour plus d’informations sur les caractères de correspondance de modèle pris en charge, consultez la section Modèles dans la documentation @actions/glob.

Exemples avec un modèle unique

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

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

Correspond à tous les fichiers .js dans le répertoire src au niveau racine, mais ignore les sous-répertoires de src.

hashFiles('/src/*.js')

Correspond à tous les fichiers .rb dans le répertoire lib au niveau racine, y compris les sous-répertoires de lib.

hashFiles('/lib/**/*.rb')

Exemples 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')

Crée un hachage pour tous les fichiers .rb dans le répertoire lib au niveau racine, y compris les sous-répertoires de lib, mais pas les fichiers .rb dans le sous-répertoire foo.

hashFiles('/lib/**/*.rb', '!/lib/foo/*.rb')

case

case( pred1, val1, pred2, val2, ..., default )

Évalue les prédicats dans l'ordre et retourne la valeur correspondant au premier prédicat qui évalue à true. Si aucun prédicat ne correspond, il retourne le dernier argument comme valeur par défaut.

Exemple avec un seul prédicat

env:
  MY_ENV_VAR: ${{ case(github.ref == 'refs/heads/main', 'production', 'development') }}

Définit MY_ENV_VAR à production lorsque la référence est refs/heads/main, sinon, la définit à development.

Exemple avec plusieurs prédicats

env:
  MY_ENV_VAR: |-
    ${{ case(
      github.ref == 'refs/heads/main', 'production',
      github.ref == 'refs/heads/staging', 'staging',
      startsWith(github.ref, 'refs/heads/feature/'), 'development',
      'unknown'
    ) }}

Définit MY_ENV_VAR en fonction de la branche : production pour main, staging pour staging, development pour les branches commençant par feature/, ou unknown pour toutes les autres branches.

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 flux de travail pour GitHub Actions et Référence syntaxique des métadonnées.

En dehors des conditions if, vous pouvez utiliser job.status pour accéder au statut de la tâche. Pour plus d’informations, consultez « Référence des contextes ».

success

Retourne true quand toutes les étapes précédentes ont réussi.

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

Avertissement

Évitez d’utiliser always pour une tâche susceptible de subir une défaillance critique, comme l’obtention de sources ; sinon, le workflow peut se bloquer jusqu’à ce qu’il arrive à expiration. Si vous souhaitez exécuter un travail ou une étape indépendamment de sa réussite ou de son échec, utilisez l’alternative recommandée : if: ${{ !cancelled() }}

Exemple de `always`

if: ${{ always() }}

annulé

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

Exemple de `cancelled`

if: ${{ cancelled() }}

failure

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.

Évaluer des expressions dans les workflows et les actions.

Dans cet article