Remarque : Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.
À 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 « Accès à des informations contextuelles sur l’exécution d’un workflow ».
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> }}
Remarque : l’exception à cette règle est l’utilisation d’expressions dans une clause if
, où, si vous le souhaitez, vous pouvez généralement omettre ${{
et }}
. Pour plus d’informations sur le conditionnel if
, consultez « Workflow syntax for 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 « Durcissement de la sécurité pour GitHub Actions ».
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. |
Remarque : dans les conditions, les valeurs false (false
, 0
, -0
, ""
, ''
, null
) sont forcées vers false
, et les valeurs true (true
et d’autres valeurs non false) 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 |
Remarques :
- 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 « Accès à des informations contextuelles sur l’exécution d’un workflow ».- 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 fonctionfromJSON()
, 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
Booléen true
retourne1
false
retourne0
String Analysé depuis n’importe quel format de nombre JSON légal ; sinon NaN
.
Remarque : une chaîne vide retourne0
.Array NaN
Object NaN
-
Quand
NaN
est l’un des opérandes d’une comparaison relationnelle (>
,<
,>=
,<=
), le résultat est toujoursfalse
. 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.
GitHub offre un comportement semblable à celui d’un opérateur ternaire que vous pouvez utiliser dans les expressions. En utilisant un opérateur ternaire de cette façon, vous pouvez définir dynamiquement la valeur d’une variable d’environnement basée sur une condition, sans avoir à écrire des blocs if-else distincts pour chaque option possible.
Exemple
env:
MY_ENV_VAR: ${{ github.ref == 'refs/heads/main' && 'value_for_main_branch' || 'value_for_other_branches' }}
Dans cet exemple, nous utilisons un opérateur ternaire pour définir la valeur de la variable d’environnement MY_ENV_VAR
selon que la référence GitHub est définie sur refs/heads/main
ou non. Si c’est le cas, la variable est définie sur value_for_main_branch
. Dans le cas contraire, elle est définie sur value_for_other_branches
.
Il est important de noter que la première valeur après &&
doit être une valeur true. Sinon, la valeur après ||
est toujours retournée.
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 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
.
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.
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 « 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
.
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 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() }}
é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.