Workflow syntax for GitHub Actions

À propos de la syntaxe YAML pour les workflows

Les fichiers de workflow utilisent la syntaxe YAML, et doivent avoir une extension de fichier .yml ou .yaml. Si vous débutez avec YAML et souhaitez en savoir plus, consultez « Découvrir YAML en Y minutes ».

Vous devez stocker les fichiers de workflow dans le répertoire .github/workflows de votre dépôt.

name

Nom du workflow. GitHub affiche les noms de vos workflows sous l’onglet « Actions » de votre référentiel. Si vous omettez name, GitHub affiche le chemin du fichier de workflow relatif à la racine du référentiel.

run-name

Nom des exécutions de workflow généré à partir du workflow. GitHub affiche le nom de l’exécution de workflow dans la liste des exécutions de workflow sous l’onglet « Actions » de votre dépôt. Si run-name est omis ou s’il est juste un espace blanc, le nom d’exécution est défini sur la base des informations spécifiques à l’événement pour l’exécution du workflow. Par exemple, pour un flux de travail déclenché par un événement push ou pull_request, il est défini comme le message de livraison ou le titre de la demande d'extraction.

Cette valeur peut inclure des expressions et peut référencer les contextes github et inputs.

Exemple de run-name

run-name: Deploy to ${{ inputs.deploy_target }} by @${{ github.actor }}

on

Pour déclencher automatiquement un workflow, utilisez on pour définir les événements qui peuvent conduire à l’exécution du workflow. Pour obtenir la liste des événements disponibles, consultez « Événements qui déclenchent des flux de travail ».

Vous pouvez définir un ou plusieurs événements susceptibles de déclencher un workflow, ou définir un calendrier. Vous pouvez également restreindre l’exécution d’un workflow de façon à ce qu’il ne se produise que pour des fichiers, étiquettes ou modifications de branche spécifiques. Les étapes de cette procédure sont décrites dans les sections suivantes.

Utilisation d’un seul événement

Par exemple, un workflow avec la valeur on suivante s’exécute quand une poussée (push) est effectuée dans une branche incluse dans son dépôt :

on: push

Utilisation de plusieurs événements

Vous pouvez spécifier un événement unique ou plusieurs événements. Par exemple, un workflow avec la valeur on suivante s’exécute quand une poussée (push) est effectuée dans une branche du dépôt ou quand quelqu’un duplique (fork) le dépôt :

on: [push, fork]

Si vous spécifiez plusieurs événements, un seul de ces événements a besoin de se produire pour déclencher votre workflow. Si plusieurs événements déclencheurs se produisent pour votre workflow en même temps, plusieurs exécutions de workflow sont déclenchées.

Utilisation de types d’activités

Certains événements ont des types d’activités qui vous donnent davantage de contrôle sur le moment où votre workflow devrait s’exécuter. Utilisez on.<event_name>.types pour définir le type d’activité d’événement qui déclenchera l’exécution d’un workflow.

Par exemple, l’événement issue_comment a les types d’activité created, edited et deleted. Si votre worflow se déclenche sur l’événement label, il s’exécute chaque fois qu’une étiquette est créée, modifiée ou supprimée. Si vous spécifiez le type d’activité created de l’événement label, votre workflow s’exécute quand une étiquette est créée, mais pas quand une étiquette est modifiée ou supprimée.

on:
  label:
    types:
      - created

Si vous spécifiez plusieurs types d’activités, un seul de ceux-ci doit se produire pour déclencher votre workflow. Si plusieurs types d’activité d’événement déclencheur pour votre workflow se produisent simultanément, plusieurs exécutions de workflow seront déclenchées. Par exemple, le workflow suivant se déclenche quand un problème est ouvert ou étiqueté. Si un problème avec deux étiquettes est ouvert, trois exécutions de workflow démarrent : une pour l’événement d’ouverture du problème, et deux pour les deux événements étiquetés du problème.

on:
  issues:
    types:
      - opened
      - labeled

Pour plus d’informations sur chaque événement et leurs types d’activité, consultez « Événements qui déclenchent des flux de travail ».

Utilisation de filtres

Certains événements comportent des filtres qui vous permettent de mieux contrôler le moment où votre workflow devrait s’exécuter.

Par exemple, l’événement push comporte un filtre branches avec lequel votre workflow ne s’exécute que lorsqu’un envoi (push) vers une branche qui correspond au filtre branches se produit, et non lorsque n’importe quel envoi se produit.

on:
  push:
    branches:
      - main
      - 'releases/**'

Utilisation de types d’activités et de filtres avec plusieurs événements

Si vous spécifiez des types d’activités ou des filtres pour un événement et que votre workflow se déclenche sur plusieurs événements, vous devez configurer chaque événement séparément. Vous devez ajouter un signe deux-points (:) à tous les événements, notamment aux événements sans configuration.

Par exemple, un workflow avec la valeur on suivante s’exécute quand :

• Une étiquette est créée.
• Une poussée (push) est effectuée dans la branche main du dépôt.
• Une poussée (push) est effectuée dans une branche compatible avec GitHub Pages.

on:
  label:
    types:
      - created
  push:
    branches:
      - main
  page_build:

on.<event_name>.types

Utilisez on.<event_name>.types pour définir le type d’activité qui déclenchera une exécution de workflow. La plupart des événements GitHub sont déclenchés par plusieurs types d’activité. Par exemple, le déclencheur label est déclenché lorsqu’une étiquette est created, editedou deleted. Le mot clé types vous permet d’affiner l’activité qui provoque l’exécution du workflow. Lorsqu’un seul type d’activité déclenche un événement de webhook, le mot clé types n’est pas nécessaire.

Vous pouvez utiliser un tableau d’événements types. Pour plus d’informations sur chaque événement et leurs types d’activité, consultez « Événements qui déclenchent des flux de travail ».

on:
  label:
    types: [created, edited]

on.<pull_request|pull_request_target>.<branches|branches-ignore>

Quand vous utilisez les événements pull_request et pull_request_target vous pouvez configurer un workflow afin qu’il s’exécute uniquement pour les demandes de tirage (pull requests) qui ciblent des branches spécifiques.

Utilisez le filtre branches quand vous souhaitez inclure des modèles de noms de branches, ou quand vous souhaitez à la fois inclure et exclure des modèles de noms de branches. Utilisez le filtre branches-ignore quand vous souhaitez exclure uniquement les modèles de nom de branche. Vous ne pouvez pas utiliser les filtres branches et branches-ignore en même temps pour le même événement dans un workflow.

Si vous définissez à la fois branches/branches-ignore et paths/paths-ignore, le workflow s’exécute uniquement quand les deux filtres sont satisfaits.

Les mots clés branches et branches-ignore acceptent les modèles Glob qui utilisent des caractères tels que *, **, +, ?, ! et certains autres pour correspondre à plusieurs noms de branches. Si un nom contient l’un de ces caractères et si vous souhaitez une correspondance littérale, vous devez utiliser le caractère d’échappement \ avec chacun de ces caractères spéciaux. Pour plus d’informations sur les modèles glob, consultez « Workflow syntax for GitHub Actions ».

Exemple : Inclusion de branches

Les modèles définis dans branches sont évalués par rapport au nom de la référence Git. Par exemple, le workflow suivant s’exécute chaque fois qu’il existe un événement pull_request pour une demande de tirage qui cible :

• Une branche nommée main (refs/heads/main)
• Une branche nommée mona/octocat (refs/heads/mona/octocat)
• Une branche dont le nom commence par releases/, par exemple releases/10 (refs/heads/releases/10)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'

Vous ne devez pas utiliser le filtrage de chemin d’accès ou de branche pour ignorer les exécutions de workflow si celui-ci est requis. Pour plus d’informations, consultez « Exécutions de workflow ignorées » et « Workflows requis ».

Si un workflow est ignoré en raison du filtrage de branche, du filtrage de chemin d’accès ou d’un message de commit, les vérifications associées à ce workflow restent alors à l’état « En attente ». La fusion d’une demande de tirage (pull request) nécessitant la réussite de ces vérifications sera bloquée.

Exemple : Exclusion de branches

Quand un modèle correspond au modèle branches-ignore, le workflow ne s’exécute pas. Les modèles définis dans branches-ignore sont évalués par rapport au nom de la référence Git. Par exemple, le workflow suivant s’exécute chaque fois qu’il existe un événement pull_request, sauf si la demande de tirage cible :

• Une branche nommée mona/octocat (refs/heads/mona/octocat)
• Une branche dont le nom correspond à releases/**-alpha, par exemple releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)

on:
  pull_request:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'

Exemple : Inclusion et exclusion de branches

Vous ne pouvez pas utiliser branches et branches-ignore pour filtrer le même événement dans un seul workflow. Si vous souhaitez à la fois inclure et exclure des modèles de branche pour un seul événement, utilisez le filtre branches avec le caractère ! pour indiquer les branches à exclure.

Si vous définissez une branche avec le caractère !, vous devez également définir au moins une branche sans le caractère !. Si vous souhaitez uniquement exclure des branches, utilisez branches-ignore à la place.

L’ordre dans lequel vous définissez les modèles est important.

• Un modèle de correspondance négative (préfixé avec !) après une correspondance positive exclut la référence Git.
• Un modèle de correspondance positive après une correspondance négative inclut à nouveau la référence Git.

Le workflow suivant s’exécute sur les événements pull_request pour les demandes de tirage qui ciblent releases/10 ou releases/beta/mona, mais pas pour les demandes de tirage qui ciblent releases/10-alpha ou releases/beta/3-alpha, car le modèle négatif !releases/**-alpha suit le modèle positif.

on:
  pull_request:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.push.<branches|tags|branches-ignore|tags-ignore>

Lorsque vous utilisez l’événement push, vous pouvez configurer un workflow pour qu’il s’exécute sur des branches ou des étiquettes spécifiques.

Utilisez le filtre branches lorsque vous souhaitez inclure des modèles de noms de branche ou lorsque vous souhaitez inclure et exclure des modèles de noms de branche. Utilisez le filtre branches-ignore quand vous souhaitez exclure uniquement les modèles de nom de branche. Vous ne pouvez pas utiliser les filtres branches et branches-ignore en même temps pour le même événement dans un workflow.

Utilisez le filtre tags lorsque vous souhaitez inclure des modèles de nom d’étiquette ou lorsque vous souhaitez inclure et exclure des modèles de noms d’étiquette. Utilisez le filtre tags-ignore lorsque vous souhaitez exclure uniquement les modèles de nom d’étiquette. Vous ne pouvez pas utiliser les filtres tags et tags-ignore en même temps pour le même événement dans un workflow.

Si vous définissez uniquement tags/tags-ignore ou uniquement branches/branches-ignore, le workflow ne s’exécutera pas pour les événements affectant la référence Git non définie. Si vous ne définissez ni tags/tags-ignore ni branches/branches-ignore, le workflow s’exécutera pour les événements affectant les branches ou les étiquettes. Si vous définissez à la fois branches/branches-ignore et paths/paths-ignore, le workflow s’exécute uniquement quand les deux filtres sont satisfaits.

Les mots clés branches, branches-ignore, tags et tags-ignore acceptent des modèles Glob qui utilisent des caractères tels que *, **, +, ?, ! et d’autres pour correspondre à plus d’un nom de branche ou d’étiquette Si un nom contient l’un de ces caractères et que vous souhaitez une correspondance littérale, vous devez échapper chacun de ces caractères spéciaux avec \. Pour plus d’informations sur les modèles glob, consultez « Workflow syntax for GitHub Actions ».

Exemple : Inclure des branches et des étiquettes

Les modèles définis dans branches et tags sont évalués par rapport au nom de la référence Git. Par exemple, le workflow suivant s’exécuterait chaque fois qu’il existe un événement push pour :

• Une branche nommée main (refs/heads/main)
• Une branche nommée mona/octocat (refs/heads/mona/octocat)
• Une branche dont le nom commence par releases/, par exemple releases/10 (refs/heads/releases/10)
• Une étiquette nommée v2 (refs/tags/v2)
• Une étiquette dont le nom commence par v1., comme v1.9.1 (refs/tags/v1.9.1)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches:
      - main
      - 'mona/octocat'
      - 'releases/**'
    # Sequence of patterns matched against refs/tags
    tags:
      - v2
      - v1.*

Exemple : Exclusion de branches et d’étiquettes

Lorsqu’un modèle correspond au modèle branches-ignore ou tags-ignore, le workflow n’est pas exécuté. Les modèles définis dans branches et tags sont évalués par rapport au nom de la référence Git. Par exemple, le workflow suivant s’exécuterait chaque fois qu’il existe un événement push, sauf si l’événement push concerne :

• Une branche nommée mona/octocat (refs/heads/mona/octocat)
• Une branche dont le nom correspond à releases/**-alpha, par exemple releases/beta/3-alpha (refs/heads/releases/beta/3-alpha)
• Une étiquette nommée v2 (refs/tags/v2)
• Une étiquette dont le nom commence par v1., comme v1.9 (refs/tags/v1.9)

on:
  push:
    # Sequence of patterns matched against refs/heads
    branches-ignore:
      - 'mona/octocat'
      - 'releases/**-alpha'
    # Sequence of patterns matched against refs/tags
    tags-ignore:
      - v2
      - v1.*

Exemple : Inclure et exclure des branches et des étiquettes

Vous ne pouvez pas utiliser branches et branches-ignore pour filtrer le même événement dans un même workflow. De même, vous ne pouvez pas utiliser tags et tags-ignore pour filtrer le même événement dans un même workflow. Si vous souhaitez inclure et exclure des modèles de branche ou d’étiquette pour un seul événement, utilisez le filtre branches ou tags avec le caractère ! pour indiquer quelles branches ou étiquettes doivent être exclues.

Si vous définissez une branche avec le caractère !, vous devez également définir au moins une branche sans caractère !. Si vous souhaitez uniquement exclure des branches, utilisez branches-ignore à la place. De même, si vous définissez une étiquette avec le caractère !, vous devez également définir au moins une étiquette sans caractère !. Si vous souhaitez uniquement exclure des étiquettes, utilisez tags-ignore à la place.

L’ordre dans lequel vous définissez les modèles est important.

• Un modèle de correspondance négative (préfixé avec !) après une correspondance positive exclut la référence Git.
• Un modèle de correspondance positive après une correspondance négative inclut à nouveau la référence Git.

Le workflow suivant s’exécute sur les envois push vers releases/10 ou releases/beta/mona, mais pas sur releases/10-alpha ou releases/beta/3-alpha parce que le modèle négatif !releases/**-alpha fait suite au modèle positif.

on:
  push:
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.<push|pull_request|pull_request_target>.<paths|paths-ignore>

Lorsque vous utilisez les événements push et pull_request événements, vous pouvez configurer un workflow pour qu’il s’exécute en fonction des chemins d’accès aux fichiers qui ont changé. Les filtres de chemin d’accès ne sont pas évalués pour les envois (push) d’étiquettes.

Utilisez le filtre paths lorsque vous souhaitez inclure des modèles de chemins d’accès aux fichiers, ou lorsque vous souhaitez à la fois inclure et exclure des modèles de modèles de chemins d’accès aux fichiers. Utilisez le filtre paths-ignore lorsque vous souhaitez uniquement exclure modèles de chemins d’accès aux fichiers. Vous ne pouvez pas utiliser les filtres paths et paths-ignore en même temps pour le même événement dans un workflow. Si vous souhaitez inclure et exclure des modèles de chemin d’accès pour un seul événement, utilisez le filtre paths avec en préfixe le caractère ! pour indiquer les chemins d’accès à exclure.

Si vous définissez à la fois branches/branches-ignore et paths/paths-ignore, le workflow s’exécute uniquement quand les deux filtres sont satisfaits.

Les mots clés paths et paths-ignore acceptent des modèles globaux qui utilisent les caractères génériques * et ** pour faire correspondre plusieurs noms de chemin d’accès. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».

Exemple : Inclusion de chemins d’accès

Si au moins un chemin d’accès correspond à un modèle dans le filtre paths, le workflow s’exécute. Par exemple, le workflow suivant s’exécuterait chaque fois que vous envoyez (push) un fichier JavaScript (.js).

on:
  push:
    paths:
      - '**.js'

Vous ne devez pas utiliser le filtrage de chemin d’accès ou de branche pour ignorer les exécutions de workflow si celui-ci est requis. Pour plus d’informations, consultez « Exécutions de workflow ignorées » et « Workflows requis ».

Si un workflow est ignoré en raison du filtrage de chemin d’accès, du filtrage de branche ou d’un message de commit, les vérifications associées à ce workflow restent alors à l’état « En attente ». La fusion d’une demande de tirage (pull request) nécessitant la réussite de ces vérifications sera bloquée.

Exemple : Exclusion de chemins d’accès

Lorsque tous les noms de chemin d’accès correspondent à des modèles dans paths-ignore, le workflow ne s’exécute pas. Si des noms de chemin d’accès ne correspondent pas à des modèles dans paths-ignore, même si certains noms de chemin d’accès correspondent aux modèles, le workflow s’exécute.

Un workflow avec le filtre de chemin d’accès suivant s’exécute uniquement sur des événements push qui incluent au moins un fichier en dehors du répertoire docs à la racine du dépôt.

on:
  push:
    paths-ignore:
      - 'docs/**'

Exemple : Inclusion et exclusion de chemins d’accès

Vous ne pouvez pas utiliser paths et paths-ignore pour filtrer le même événement dans un seul workflow. Si vous souhaitez inclure et exclure des modèles de chemin d’accès pour un seul événement, utilisez le filtre paths avec en préfixe le caractère ! pour indiquer les chemins d’accès à exclure.

Si vous définissez un chemin d’accès avec le caractère !, vous devez également définir au moins un chemin d’accès sans caractère !. Si vous souhaitez uniquement exclure des chemins d’accès, utilisez plutôt paths-ignore.

L’ordre dans lequel vous définissez les modèles paths est important :

• Un modèle négatif de correspondance (préfixé avec !) après une correspondance positive exclut le chemin d’accès.
• Un modèle positif de correspondance après une correspondance négative inclut à nouveau le chemin d’accès.

Cet exemple s’exécute à chaque fois que l’événement push inclut un fichier dans le répertoire sub-project ou ses sous-répertoires, sauf si le fichier se trouve dans le répertoire sub-project/docs. Par exemple, un envoi (push) qui change sub-project/index.js ou sub-project/src/index.js déclenche l’exécution d’un workflow, au contraire d’un envoi (push) changeant uniquement sub-project/docs/readme.md.

on:
  push:
    paths:
      - 'sub-project/**'
      - '!sub-project/docs/**'

Comparaisons de différences Git

Le filtre détermine si un workflow doit s’exécuter en évaluant les fichiers modifiés et en les exécutant sur la liste paths-ignore ou paths. S’il n’y a pas de fichier modifié, le workflow ne s’exécute pas.

GitHub génère la liste des fichiers modifiés à l’aide de différences de deux points pour les envois (push) et de différences de trois points pour les demandes de tirage :

• Demandes de tirage : les différences de trois points sont une comparaison entre la version la plus récente de la branche de rubrique, et la validation dans laquelle la branche de rubrique a été synchronisée pour la dernière fois avec la branche de base.
• Envois (push) à des branches existantes : une différence de deux points compare directement les SHA principal et de base.
• Envois (push) à nouvelles branches : une différence de deux points par rapport au parent de l’élément ancêtre de la validation la plus profonde envoyées (push).

Les différences sont limitées à 300 fichiers. S’il y a des fichiers modifiés qui ne sont pas mis en correspondance dans les 300 premiers fichiers retournés par le filtre, le workflow n’est pas exécuté. Il se peut que vous deviez créer des filtres plus spécifiques afin que le workflow s’exécute automatiquement.

Pour plus d’informations, consultez « À propos de la comparaison des branches dans les demandes de tirage ».

on.schedule

Vous pouvez utiliser on.schedule pour définir un calendrier pour vos workflows. Vous pouvez planifier l’exécution d’un workflow à des heures UTC spécifiques à l’aide de la syntaxe cron POSIX. Les workflows planifiés s’exécutent sur le dernier commit de la branche par défaut ou de base. L’intervalle le plus court auquel vous pouvez exécuter des workflows planifiés est une fois toutes les 5 minutes.

Cet exemple déclenche le workflow chaque jour à 5h30 et à 17h30 UTC :

on:
  schedule:
    # * is a special character in YAML so you have to quote this string
    - cron:  '30 5,17 * * *'

Un seul workflow peut être déclenché par plusieurs événements schedule. Vous pouvez accéder à l’événement de planification qui a déclenché le workflow via le contexte github.event.schedule. Cet exemple déclenche l’exécution du workflow à 5h30 UTC tous les lundis et jeudis, mais ignore l’étape Not on Monday or Wednesday le lundi et le mercredi.

on:
  schedule:
    - cron: '30 5 * * 1,3'
    - cron: '30 5 * * 2,4'

jobs:
  test_schedule:
    runs-on: ubuntu-latest
    steps:
      - name: Not on Monday or Wednesday
        if: github.event.schedule != '30 5 * * 1,3'
        run: echo "This step will be skipped on Monday and Wednesday"
      - name: Every time
        run: echo "This step will always run"

Pour plus d’informations sur la syntaxe cron, consultez « Événements qui déclenchent des flux de travail ».

on.workflow_call

Utilisez on.workflow_call pour définir les entrées et sorties d’un workflow réutilisable. Vous pouvez également mapper les secrets disponibles au workflow appelé. Pour plus d’informations sur les workflows réutilisables, consultez « Réutilisation des workflows ».

on.workflow_call.inputs

Lorsque vous utilisez le mot clé workflow_call, vous pouvez éventuellement spécifier des entrées qui sont passées au workflow appelé à partir du workflow appelant. Pour plus d’informations sur le mot clé workflow_call, consultez « Événements qui déclenchent des flux de travail ».

En plus des paramètres d’entrée standard disponibles, on.workflow_call.inputs nécessite un paramètre type. Pour plus d’informations, consultez on.workflow_call.inputs.<input_id>.type.

Si aucun paramètre default n’est défini, la valeur par défaut de l’entrée est false pour une valeur booléenne, 0 pour un nombre et "" pour une chaîne.

Dans le workflow appelé, vous pouvez utiliser le contexte inputs pour référencer une entrée. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Si un workflow appelant passe une entrée qui n’est pas spécifiée dans le workflow appelé, cela entraîne une erreur.

Exemple de on.workflow_call.inputs

on:
  workflow_call:
    inputs:
      username:
        description: 'A username passed from the caller workflow'
        default: 'john-doe'
        required: false
        type: string

jobs:
  print-username:
    runs-on: ubuntu-latest

    steps:
      - name: Print the input name to STDOUT
        run: echo The username is ${{ inputs.username }}

Pour plus d’informations, consultez « Réutilisation des workflows ».

on.workflow_call.inputs.<input_id>.type

Obligatoire si l’entrée est définie pour le mot clé on.workflow_call. La valeur de ce paramètre est une chaîne spécifiant le type de données de l’entrée. Il doit s’agir de l’une des valeurs suivantes : boolean, number ou string.

on.workflow_call.outputs

Mappage des sorties pour un workflow appelé. Les sorties de workflow appelé sont disponibles pour tous les travaux en aval dans le workflow appelant. Chaque sortie a un identificateur, une description, facultative et une valeur (value.). value doit être définie sur la valeur d’une sortie d’un travail dans le workflow appelé.

Dans l’exemple ci-dessous, deux sorties sont définies pour ce workflow réutilisable : workflow_output1 et workflow_output2. Celles-ci sont mappées aux sorties appelées job_output1 et job_output2, toutes les deux provenant d’un travail appelé my_job.

Exemple de on.workflow_call.outputs

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      workflow_output1:
        description: "The first job output"
        value: ${{ jobs.my_job.outputs.job_output1 }}
      workflow_output2:
        description: "The second job output"
        value: ${{ jobs.my_job.outputs.job_output2 }}

Pour plus d’informations sur la façon de référencer une sortie de travail, consultez jobs.<job_id>.outputs. Pour plus d’informations, consultez « Réutilisation des workflows ».

on.workflow_call.secrets

Mappage des secrets qui peuvent être utilisés dans le workflow appelé.

Dans le workflow appelé, vous pouvez utiliser le contexte secrets pour référencer un secret.

Si un workflow appelant passe un secret qui n’est pas spécifié dans le workflow appelé, cela entraîne une erreur.

Exemple de on.workflow_call.secrets

on:
  workflow_call:
    secrets:
      access-token:
        description: 'A token passed from the caller workflow'
        required: false

jobs:

  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
    # passing the secret to an action
      - name: Pass the received secret to an action
        uses: ./.github/actions/my-action
        with:
          token: ${{ secrets.access-token }}

  # passing the secret to a nested reusable workflow
  pass-secret-to-workflow:
    uses: ./.github/workflows/my-workflow
    secrets:
       token: ${{ secrets.access-token }}

on.workflow_call.secrets.<secret_id>

Identificateur de chaîne à associer au secret.

on.workflow_call.secrets.<secret_id>.required

Valeur booléenne spécifiant si le secret doit être fourni.

on.workflow_run.<branches|branches-ignore>

Lorsque vous utilisez l’événement workflow_run, vous pouvez spécifier les branches sur lesquelles le workflow déclencheur doit s’exécuter afin de déclencher votre workflow.

Les filtres branches et branches-ignore acceptent les modèles Glob qui utilisent des caractères tels que *, **, +, ?, ! et certains autres pour correspondre à plusieurs noms de branches. Si un nom contient l’un de ces caractères et que vous souhaitez une correspondance littérale, vous devez échapper chacun de ces caractères spéciaux avec \. Pour plus d’informations sur les modèles glob, consultez « Workflow syntax for GitHub Actions ».

Par exemple, un workflow avec le déclencheur suivant s’exécute uniquement lorsque le workflow nommé Build s’exécute sur une branche dont le nom commence par releases/ :

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'

Un workflow avec le déclencheur suivant s’exécute uniquement lorsque le workflow nommé Build s’exécute sur une branche qui n’est pas nommée canary :

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches-ignore:
      - "canary"

Vous ne pouvez pas utiliser les filtres branches et branches-ignore en même temps pour le même événement dans un workflow. Si vous souhaitez à la fois inclure et exclure des modèles de branche pour un seul événement, utilisez le filtre branches avec le caractère ! pour indiquer les branches à exclure.

L’ordre dans lequel vous définissez les modèles est important.

• Un modèle négatif de correspondance (préfixé avec !) après une correspondance positive exclut la branche.
• Un modèle positif de correspondance après une correspondance négative inclut à nouveau la branche.

Par exemple, un workflow avec le déclencheur suivant s’exécute lorsque le workflow nommé Build s’exécute sur une branche nommée releases/10 ou releases/beta/mona, mais pas releases/10-alpha, releases/beta/3-alpha ni main.

on:
  workflow_run:
    workflows: ["Build"]
    types: [requested]
    branches:
      - 'releases/**'
      - '!releases/**-alpha'

on.workflow_dispatch

Quand vous utilisez l’événement workflow_dispatch, vous pouvez éventuellement spécifier des entrées qui sont passées au workflow.

Ce déclencheur reçoit uniquement les événements lorsque le fichier de flux de travail se trouve sur la branche par défaut.

on.workflow_dispatch.inputs

Le workflow déclenché reçoit les entrées dans le contexte inputs. Pour plus d’informations, consultez « Contextes ».

Exemple de on.workflow_dispatch.inputs

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
        type: choice
        options:
          - info
          - warning
          - debug
      print_tags:
        description: 'True to print to STDOUT'
        required: true
        type: boolean
      tags:
        description: 'Test scenario tags'
        required: true
        type: string
      environment:
        description: 'Environment to run tests against'
        type: environment
        required: true

jobs:
  print-tag:
    runs-on: ubuntu-latest
    if:  ${{ inputs.print_tags }} 
    steps:
      - name: Print the input tag to STDOUT
        run: echo  The tags are ${{ inputs.tags }} 

on.workflow_dispatch.inputs.<input_id>.required

Valeur booléenne spécifiant si l’entrée doit être fournie.

on.workflow_dispatch.inputs.<input_id>.type

La valeur de ce paramètre est une chaîne spécifiant le type de données de l’entrée. Il doit s’agir de l’une des valeurs suivantes : boolean, choice, number, environment ou string.

permissions

Vous pouvez utiliser permissions pour modifier les autorisations par défaut octroyées à GITHUB_TOKEN, en ajoutant ou en supprimant l’accès selon les besoins, afin d’autoriser uniquement l’accès minimal nécessaire. Pour plus d’informations, consultez « Authentification par jeton automatique ».

Vous pouvez utiliser permissions en tant que clé de niveau supérieur, à appliquer à tous les travaux du workflow ou à des travaux spécifiques. Quand vous ajoutez la clé permissions à un travail spécifique, toutes les actions et commandes d’exécution de ce travail qui utilisent GITHUB_TOKEN obtiennent les droits d’accès que vous spécifiez. Pour plus d’informations, consultez jobs.<job_id>.permissions.

Pour chacune des autorisations disponibles, indiquées sur la table ci-dessous, vous pouvez attribuer l’un des niveaux d’accès : read (le cas échéant), write ou none. write comprend read. Si vous spécifiez l’accès pour l’une de ces autorisations, toutes celles qui ne sont pas spécifiées sont définies sur none.

Autorisations disponibles et détails de ce que chacune permet à une action d’effectuer :

Définition de l’accès pour les étendues GITHUB_TOKEN

Vous pouvez définir l’accès que le GITHUB_TOKEN autorise en spécifiant read, write ou none comme valeur des autorisations disponibles dans la clé permissions.

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Si vous spécifiez l’accès pour l’une de ces autorisations, toutes celles qui ne sont pas spécifiées sont définies sur none.

Vous pouvez utiliser la syntaxe suivante pour définir l'un des accès read-all ou write-all à toutes les autorisations disponibles :

permissions: read-all

permissions: write-all

Vous pouvez utiliser la syntaxe suivante afin de désactiver les autorisations pour toutes les autorisations disponibles :

permissions: {}

Modification des autorisations dans un référentiel dupliqué

Vous pouvez utiliser la clé permissions afin d’ajouter et de supprimer des autorisations d’accès en lecture pour les dépôts dupliqués. Toutefois, en règle générale, vous ne pouvez pas octroyer d’accès en écriture. Il existe une exception à ce comportement. Il s’agit du moment où un utilisateur administrateur a sélectionné l’option Envoyer des jetons d’écriture aux workflows à partir des demandes de tirage dans les paramètres de GitHub Actions. Pour plus d’informations, consultez « Gestion des paramètres de GitHub Actions pour un dépôt ».

Définition des autorisations GITHUB_TOKEN pour tous les travaux d’un workflow

Vous pouvez spécifier permissions au niveau supérieur d’un workflow, afin que le paramètre s’applique à tous les travaux du workflow.

Exemple : définition des autorisations GITHUB_TOKEN pour un workflow entier

Cet exemple montre les autorisations définies pour GITHUB_TOKEN, qui s’appliquent à tous les travaux du workflow. Toutes les autorisations se voient octroyer un accès en lecture.

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

Mappage (map) des variables qui sont disponibles pour les étapes de tous les travaux du workflow. Vous pouvez également définir des variables qui sont disponibles uniquement pour les étapes d’un seul travail ou pour une seule étape. Pour plus d’informations, consultez jobs.<job_id>.env et jobs.<job_id>.steps[*].env.

Les variables du mappage env ne peuvent pas être définies d’après d’autres variables du mappage.

Quand plusieurs variables d’environnement sont définies avec le même nom, GitHub utilise la variable la plus spécifique. Par exemple, une variable d’environnement définie dans une étape remplace les variables d’environnement du travail et du workflow portant le même nom, pendant l’exécution de l’étape. Une variable d’environnement définie pour un travail remplace une variable de workflow de même nom, pendant l’exécution du travail.

Exemple de env

env:
  SERVER: production

defaults

Utilisez defaults pour créer un map de paramètres par défaut qui s’appliqueront à tous les travaux du workflow. Vous pouvez également définir des paramètres par défaut uniquement disponibles pour un travail. Pour plus d’informations, consultez jobs.<job_id>.defaults.

Quand plusieurs paramètres par défaut sont définis avec le même nom, GitHub utilise le paramètre par défaut le plus spécifique. Par exemple, un paramètre par défaut défini dans un travail remplace un paramètre par défaut portant le même nom défini dans un workflow.

defaults.run

Vous pouvez utiliser defaults.run afin de fournir les options shell et working-directory par défaut pour toutes les étapes run d’un workflow. Vous pouvez également définir pour run des paramètres par défaut qui sont disponibles uniquement pour un travail. Pour plus d’informations, consultez jobs.<job_id>.defaults.run. Vous ne pouvez pas utiliser de contextes ou d’expressions dans ce mot clé.

Quand plusieurs paramètres par défaut sont définis avec le même nom, GitHub utilise le paramètre par défaut le plus spécifique. Par exemple, un paramètre par défaut défini dans un travail remplace un paramètre par défaut portant le même nom défini dans un workflow.

Exemple : Définir l’interpréteur de commandes et le répertoire de travail par défaut

defaults:
  run:
    shell: bash
    working-directory: ./scripts

defaults.run.shell

Utilise shell pour définir le shell d'une étape. Ce mot clé peut référencer plusieurs contextes. Pour plus d’informations, consultez « Contextes ».

Quand plusieurs paramètres par défaut sont définis avec le même nom, GitHub utilise le paramètre par défaut le plus spécifique. Par exemple, un paramètre par défaut défini dans un travail remplace un paramètre par défaut portant le même nom défini dans un workflow.

defaults.run.working-directory

Utilise working-directory pour définir le répertoire de travail pour le shell d'une étape. Ce mot clé peut référencer plusieurs contextes. Pour plus d’informations, consultez « Contextes ».

concurrency

Utilisez concurrency pour vérifier qu’un seul travail ou workflow utilisant le même groupe d’accès concurrentiel s’exécute à la fois. Un groupe d’accès concurrentiel peut correspondre à n’importe quelle chaîne ou expression. L’expression peut uniquement utiliser les contextes github, inputs et vars. Pour plus d’informations sur les expressions, consultez « Évaluer les expressions dans les workflows et les actions ».

Vous pouvez également spécifier concurrency au niveau du travail. Pour plus d’informations, consultez jobs.<job_id>.concurrency.

Cela signifie qu’il peut y avoir au plus un travail en cours d’exécution et un travail en attente dans un groupe d’accès concurrentiel à tout moment. Quand un travail ou un workflow simultané est mis en file d’attente, si un autre travail ou workflow utilisant le même groupe d’accès concurrentiel dans le dépôt est en cours d’exécution, le travail ou le workflow en file d’attente a la valeur pending. Tout travail pending ou flux de travail existant dans le même groupe d’accès concurrentiel, s’il existe, sera annulé et le nouveau travail ou flux de travail mis en file d’attente aura lieu.

Pour annuler également un travail ou un workflow en cours d’exécution dans le même groupe d’accès concurrentiel, spécifiez cancel-in-progress: true. Pour annuler de façon conditionnelle les travaux ou les flux de travail en cours d’exécution dans le même groupe d’accès concurrentiel, vous pouvez spécifier cancel-in-progress en tant qu’expression avec l’un des contextes d’expression autorisés.

Exemple : utilisation de la concurrence et du comportement par défaut

Le comportement par défaut de GitHub Actions consiste à autoriser l'exécution simultanée de plusieurs projets ou les exécutions de flux de travail. Le mot clé concurrency vous permet de contrôler la concurrence des exécutions de flux de travail.

Par exemple, vous pouvez utiliser le mot clé concurrency immédiatement après le lieu de définition des conditions de déclenchement afin de limiter la concurrence des exécutions de l'ensemble du flux de travail pour une branche spécifique :

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Vous pouvez également limiter la concurrence des projets au sein d'un flux de travail en utilisant le mot-clé concurrency au niveau du projet :

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

Exemple : groupes de concurrence

Les groupes de concurrence permettent de gérer et de limiter l'exécution des flux de travail ou des projets qui partagent la même clé de concurrence.

La clé concurrency est utilisée pour regrouper des flux de travail ou des projets ensemble dans un groupe de concurrence. Lorsque vous définissez une clé concurrency, GitHub Actions garantit qu'un seul flux de travail ou projet avec cette clé s'exécute à tout moment. Si une exécution de flux de travail ou un projet est à nouveau lancé(e) avec la même clé concurrency, GitHub Actions annule tout flux de travail ou projet déjà en cours d'exécution avec cette clé. La clé concurrency peut être une chaîne codée en dur, ou il peut s'agir d'une expression dynamique qui inclut des variables de contexte.

Il est possible de définir des conditions de concurrence dans votre flux de travail afin que le flux de travail ou le projet fasse partie d'un groupe de concurrence.

En d'autres termes, lorsqu'un flux de travail ou un projet est lancé, GitHub annule tous les flux de travail ou projets déjà en cours dans le même groupe de concurrence. Cette fonction est utile dans les scénarios où vous souhaitez empêcher les exécutions parallèles pour un certain ensemble de flux de travail ou de projets, comme ceux utilisés pour les déploiements dans un environnement intermédiaire, afin d'éviter les actions susceptibles de provoquer des conflits ou de consommer plus de ressources qu'il n'est nécessaire.

Dans cet exemple, job-1 fait partie d'un groupe de concurrence nommé staging_environment. En d'autres termes, si une nouvelle exécution de job-1 est déclenchée, toutes les exécutions du même projet dans le groupe de concurrence staging_environment qui sont déjà en cours seront annulées.

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

Par ailleurs, l'utilisation d'une expression dynamique comme concurrency: ci-${{ github.ref }} dans votre flux de travail signifie que le flux de travail ou le projet fera partie d'un groupe de concurrence dont le nom ci- est suivi de la référence de la branche ou de la balise qui a déclenché le flux de travail. Dans cet exemple, si un nouvel engagement est envoyé vers la branche primaire alors qu'une exécution précédente est toujours en cours, cette dernière sera annulée et la nouvelle lancée :

on:
  push:
    branches:
      - main

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

Exemple : Utilisation de la concurrence pour annuler un travail ou une exécution en cours

Pour utiliser la concurrence afin d'annuler un projet en cours ou une exécution dans GitHub Actions, vous pouvez utiliser la clé concurrency avec l'option cancel-in-progress définie sur true :

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Notez que dans cet exemple, sans définir un groupe de concurrence particulier, GitHub Actions annulera toute exécution en cours du projet ou du flux de travail.

Exemple : Utilisation d’une valeur de secours

Si vous créez le nom de groupe avec une propriété définie uniquement pour des événements spécifiques, vous pouvez utiliser une valeur de secours. Par exemple, github.head_ref est défini uniquement pour les événements pull_request. Si votre workflow répond à d’autres événements en plus des événements pull_request, vous devez fournir une valeur de secours pour éviter une erreur de syntaxe. Le groupe d’accès concurrentiel suivant annule les travaux ou les exécutions en cours pour les événements pull_request uniquement. Si github.head_ref n’est pas défini, le groupe d’accès concurrent utilise l’ID d’exécution, qui offre la garantie d’être à la fois unique et défini pour l’exécution.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Exemple : Annuler uniquement les travaux ou les exécutions en cours pour le workflow actuel

Si vous avez plusieurs workflows dans le même dépôt, les noms de groupes d’accès concurrentiel doivent être uniques au sein de tous les workflows pour éviter l’annulation de travaux ou d’exécutions en cours à partir d’autres workflows. Sinon, tout travail en cours ou en attente est annulé, quel que soit le workflow.

Pour annuler uniquement les exécutions en cours du même workflow, vous pouvez utiliser la propriété github.workflow afin de créer le groupe d’accès concurrentiel :

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Exemple : Annuler uniquement les travaux en cours sur des branches spécifiques

Si vous souhaitez annuler des travaux en cours sur certaines branches, mais pas sur d’autres, vous pouvez utiliser des expressions conditionnelles avec cancel-in-progress. Par exemple, vous pouvez procéder ainsi si vous souhaitez annuler les travaux en cours sur les branches de développement, mais pas sur les branches de publication.

Pour n’annuler que les exécutions en cours du même workflow lorsqu’il n’est pas exécuté sur une branche de publication, vous pouvez définir cancel-in-progress comme une expression similaire à la suivante :

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'release/')}}

Dans cet exemple, plusieurs envois push vers une branche release/1.2.3 n’annulent pas les exécutions en cours. Les envois (push) vers une autre branche, par exemple main, annulent les exécutions en cours.

jobs

Une exécution de workflow est composée d’un ou de plusieurs jobs, qui s’exécutent en parallèle par défaut. Pour exécuter des travaux de manière séquentielle, vous pouvez définir des dépendances par rapport à d’autres travaux à l’aide du mot clé jobs.<job_id>.needs.

Chaque travail s’exécute dans un environnement d’exécuteur spécifié par runs-on.

Vous pouvez exécuter un nombre illimité de travaux tant que vous respectez les limites d’utilisation du workflow. Pour plus d’informations, consultez « Limites d’utilisation, facturation et administration » pour les exécuteurs hébergés par GitHub et À propos des exécuteurs auto-hébergés » pour les limites d’utilisation des exécuteurs auto-hébergés.

Si vous devez trouver l’identificateur unique d’un travail en cours d’exécution dans une exécution de workflow, vous pouvez utiliser l’API GitHub Enterprise Server. Pour plus d’informations, consultez « Points de terminaison REST pour l’API GitHub Actions ».

jobs.<job_id>

Utilisez jobs.<job_id> pour attribuer un identificateur unique à votre travail. La clé job_id est une chaîne et sa valeur est une carte des données de configuration du travail. Vous devez remplacer <job_id> par une chaîne propre à l’objet jobs. <job_id> doit commencer par une lettre ou par _, et contenir uniquement des caractères alphanumériques, des - ou des _.

Exemple : Création de travaux

Dans cet exemple, deux travaux ont été créés, et leurs valeurs job_id sont my_first_job et my_second_job.

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

jobs.<job_id>.name

Utilisez jobs.<job_id>.name pour définir un nom pour le travail, qui s’affiche sur l’interface utilisateur GitHub.

jobs.<job_id>.permissions

Pour un travail spécifique, vous pouvez utiliser jobs.<job_id>.permissions afin de modifier les autorisations par défaut octroyées à GITHUB_TOKEN, en ajoutant ou en supprimant l’accès selon les besoins, afin d’autoriser uniquement l’accès minimal nécessaire. Pour plus d’informations, consultez « Authentification par jeton automatique ».

En spécifiant l’autorisation dans une définition de travail, vous pouvez configurer un ensemble d’autorisations différent pour le GITHUB_TOKEN de chaque travail, le cas échéant. Vous pouvez également spécifier les autorisations relatives à tous les travaux du workflow. Pour plus d’informations sur la définition d’autorisations au niveau du workflow, consultez permissions.

Pour chacune des autorisations disponibles, indiquées sur la table ci-dessous, vous pouvez attribuer l’un des niveaux d’accès : read (le cas échéant), write ou none. write comprend read. Si vous spécifiez l’accès pour l’une de ces autorisations, toutes celles qui ne sont pas spécifiées sont définies sur none.

Autorisations disponibles et détails de ce que chacune permet à une action d’effectuer :

Définition de l’accès pour les étendues GITHUB_TOKEN

Vous pouvez définir l’accès que le GITHUB_TOKEN autorise en spécifiant read, write ou none comme valeur des autorisations disponibles dans la clé permissions.

permissions:
  actions: read|write|none
  checks: read|write|none
  contents: read|write|none
  deployments: read|write|none
  issues: read|write|none
  discussions: read|write|none
  packages: read|write|none
  pages: read|write|none
  pull-requests: read|write|none
  repository-projects: read|write|none
  security-events: read|write|none
  statuses: read|write|none

Si vous spécifiez l’accès pour l’une de ces autorisations, toutes celles qui ne sont pas spécifiées sont définies sur none.

Vous pouvez utiliser la syntaxe suivante pour définir l'un des accès read-all ou write-all à toutes les autorisations disponibles :

permissions: read-all

permissions: write-all

Vous pouvez utiliser la syntaxe suivante afin de désactiver les autorisations pour toutes les autorisations disponibles :

permissions: {}

Modification des autorisations dans un référentiel dupliqué

Vous pouvez utiliser la clé permissions afin d’ajouter et de supprimer des autorisations d’accès en lecture pour les dépôts dupliqués. Toutefois, en règle générale, vous ne pouvez pas octroyer d’accès en écriture. Il existe une exception à ce comportement. Il s’agit du moment où un utilisateur administrateur a sélectionné l’option Envoyer des jetons d’écriture aux workflows à partir des demandes de tirage dans les paramètres de GitHub Actions. Pour plus d’informations, consultez « Gestion des paramètres de GitHub Actions pour un dépôt ».

Exemple : définition des autorisations GITHUB_TOKEN pour un travail dans un workflow

Cet exemple montre les autorisations définies pour GITHUB_TOKEN, qui s’appliquent uniquement au travail nommé stale. L’accès en écriture est octroyé pour les autorisations issues et pull-requests. Toutes les autres autorisations n’ont aucun accès.

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v5

jobs.<job_id>.needs

Utilisez jobs.<job_id>.needs pour identifier les travaux à accomplir avant l’exécution de ce travail. Il peut s’agir d’une chaîne ou d’un tableau de chaînes. Si un travail échoue ou est ignoré, tous les travaux qui besoin de celui-ci sont ignorés, sauf s’ils utilisent une expression conditionnelle entraînant la poursuite du travail. Si une exécution contient une série de travaux qui ont besoin l’un de l’autre, une défaillance ou l’action d’ignorer s’applique à tous les travaux de la chaîne de dépendance à partir du point en question. Si vous souhaitez qu’un travail s’exécute même si un travail dont il dépend n’a pas réussi, utilisez l’expression conditionnelle always() dans jobs.<job_id>.if.

Exemple : Exigence de réussite de travaux dépendants

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

Dans cet exemple, job1 doit être correctement accompli avant que job2 commence, et job3 attend que job1 et job2 soient accomplis.

Les travaux dans cet exemple s’exécutent séquentiellement :

1. job1
2. job2
3. job3

Exemple : Non-exigence de réussite de travaux dépendants

jobs:
  job1:
  job2:
    needs: job1
  job3:
    if: ${{ always() }}
    needs: [job1, job2]

Dans cet exemple, job3 utilise l’expression conditionnelle always() afin de toujours s’exécuter après que job1 et job2 ont été effectués avec ou sans succès. Pour plus d’informations, consultez « Évaluer les expressions dans les workflows et les actions ».

jobs.<job_id>.if

Vous pouvez utiliser le jobs.<job_id>.if conditionnel pour empêcher l’exécution d’un travail, sauf si une condition est remplie. Vous pouvez utiliser n’importe quel contexte et n’importe quelle expression pris en charge pour créer un conditionnel. Pour plus d’informations sur les contextes pris en charge dans cette clé, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Quand vous utilisez des expressions dans un conditionnel if, vous pouvez omettre la syntaxe de l’expression ${{ }} parce que GitHub Actions évalue automatiquement le conditionnel if en tant qu’expression. Toutefois, cette exception ne s’applique pas partout.

Vous devez utiliser la syntaxe d’expression ${{ }} ou l’échappement avec '', "" ou () lorsque l’expression commence par !, car ! est une notation réservée au format YAML. Par exemple :

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

Pour plus d’informations, consultez « Évaluer les expressions dans les workflows et les actions ».

Exemple : Exécuter un travail uniquement pour un dépôt spécifique

Cet exemple utilise if pour contrôler le moment où le travail production-deploy peut s’exécuter. Il s’exécute uniquement si le dépôt se nomme octo-repo-prod, et s’il se trouve dans l’organisation octo-org. Sinon, le travail est marqué comme étant ignoré.

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats

name: example-workflow
on: [push]
jobs:
  production-deploy:
    if: github.repository == 'octo-org/octo-repo-prod'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats

jobs.<job_id>.runs-on

Utilisez jobs.<job_id>.runs-on pour définir le type de machine sur laquelle le travail doit être exécuté.

• La machine de destination peut être un exécuteur auto-hébergé.

• Vous pouvez cibler des exécuteurs en fonction des étiquettes qui leur sont affectées et/ou de leur appartenance au groupe.

• Vous pouvez fournir runs-on sous la forme suivante :

  • Une seule chaîne
  • Une seule variable contenant une chaîne
  • Un tableau de chaînes, des variables contenant des chaînes ou une combinaison des deux
  • Une paire key: value utilisant les clés group ou labels

• Si vous spécifiez un tableau de chaînes ou de variables, votre workflow s’exécute sur n’importe quel exécuteur correspondant à toutes les valeurs runs-on spécifiées. Par exemple, ici, le travail s’exécute uniquement sur un exécuteur auto-hébergé qui a les étiquettes linux, x64 et gpu :

  runs-on: [self-hosted, linux, x64, gpu]
  

  Pour plus d’informations, consultez « Choix d’exécuteurs auto-hébergés ».

• Vous pouvez mélanger des chaînes et des variables dans un tableau. Par exemple :

  on:
    workflow_dispatch:
      inputs:
        chosen-os:
          required: true
          type: choice
          options:
          - Ubuntu
          - macOS
  
  jobs:
    test:
      runs-on: [self-hosted, "${{ inputs.chosen-os }}"]
      steps:
      - run: echo Hello world!
  

• Si vous souhaitez exécuter votre workflow sur plusieurs machines, utilisez jobs.<job_id>.strategy.

Choix des exécuteurs hébergés par GitHub

Choix des exécuteurs auto-hébergés

Si vous souhaitez spécifier un exécuteur autohébergé pour votre travail, configurez runs-on dans votre fichier de workflow avec des étiquettes d’exécuteur autohébergé.

Les exécuteurs auto-hébergés sont susceptibles d’avoir l’étiquette self-hosted. Lors de la configuration d’un exécuteur auto-hébergé, nous inclurons l’étiquette self-hosted par défaut. Vous pouvez passer l’indicateur --no-default-labels pour empêcher l’application de l’étiquette d’auto-hébergement. Les étiquettes peuvent être utilisées pour créer des options de ciblage pour les exécuteurs, telles que le système d’exploitation ou l’architecture. Nous recommandons de fournir un tableau d’étiquettes qui commence par self-hosted (ceci doit être listé en premier) et inclut ensuite des étiquettes supplémentaires si nécessaire. Quand vous spécifiez un tableau d’étiquettes, les travaux sont mis en file d’attente sur des exécuteurs qui comportent toutes les étiquettes que vous indiquez.

Notez qu’Actions Runner Controller ne prend pas en charge plusieurs étiquettes et ne prend pas en charge l’étiquette self-hosted.

Exemple : Utilisation d’étiquettes pour la sélection des exécuteurs

runs-on: [self-hosted, linux]

Pour plus d’informations, consultez « À propos des exécuteurs auto-hébergés » et « Utilisation d’exécuteurs auto-hébergés dans un workflow ».

Choix des exécuteurs dans un groupe

Vous pouvez utiliser runs-on pour cibler des groupes d’exécuteurs, afin que le travail s’exécute sur n’importe quel exécuteur membre de ce groupe. Pour un contrôle plus précis, vous pouvez également combiner des groupes d’exécuteurs avec des étiquettes.

Exemple : utilisation de groupes pour contrôler où les travaux sont exécutés

Dans cet exemple, des exécuteurs Ubuntu ont été ajoutés à un groupe appelé ubuntu-runners. La clé runs-on envoie le travail à n’importe quel exécuteur disponible dans le groupe ubuntu-runners :

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on: 
      group: ubuntu-runners
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

Exemple : combinaison de groupes et d’étiquettes

Quand vous combinez des groupes et des étiquettes, l’exécuteur doit satisfaire aux deux exigences pour pouvoir exécuter le travail.

Dans cet exemple, un groupe d’exécuteurs appelé ubuntu-runners est rempli avec des exécuteurs Ubuntu, qui ont également reçu l’étiquette ubuntu-20.04-16core. La clé runs-on combine group et labels afin que le travail soit routé vers n’importe quel exécuteur disponible au sein du groupe qui a également une étiquette correspondante :

name: learn-github-actions
on: [push]
jobs:
  check-bats-version:
    runs-on:
      group: ubuntu-runners
      labels: ubuntu-20.04-16core
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm install -g bats
      - run: bats -v

Exemple : utilisation de préfixes pour différencier les groupes d’exécuteurs

Par exemple, si vous avez un groupe d’exécuteurs nommé my-group dans l’organisation et un autre nommé my-group dans l’entreprise, vous pouvez mettre à jour votre fichier de workflow pour utiliser org/my-group ou ent/my-group afin de les différencier.

Utilisation de org/:

runs-on:
  group: org/my-group
  labels: [ self-hosted, label-1 ]

Utilisation de ent/:

runs-on:
  group: ent/my-group
  labels: [ self-hosted, label-1 ]

jobs.<job_id>.environment

Utilisez jobs.<job_id>.environment pour définir l’environnement référencé par le travail.

Vous pouvez fournir l’environnement en tant qu’environnement name uniquement, ou en tant qu’objet d’environnement avec name et url. L’URL est mappée à environment_url dans l’API des déploiements. Pour plus d’informations sur l’API des déploiements, consultez « Points de terminaison d’API REST pour les référentiels ».

Exemple : Utilisation d’un seul nom d’environnement

environment: staging_environment

Exemple : Utilisation du nom et de l’URL de l’environnement

environment:
  name: production_environment
  url: https://github.com

La valeur de url peut être une expression. Contextes d’expression autorisés : github, inputs, vars, needs, strategy, matrix, job, runner, env et steps. Pour plus d’informations sur les expressions, consultez « Évaluer les expressions dans les workflows et les actions ».

Exemple : Utilisation de la sortie en tant qu’URL

environment:
  name: production_environment
  url: ${{ steps.step_id.outputs.url_output }}

La valeur de name peut être une expression. Contextes d’expression autorisés : github, inputs, vars, needs, strategy et matrix. Pour plus d’informations sur les expressions, consultez « Évaluer les expressions dans les workflows et les actions ».

Exemple : Utilisation d’une expression comme nom d’environnement

environment:
  name: ${{ github.ref_name }}

jobs.<job_id>.concurrency

Vous pouvez utiliser jobs.<job_id>.concurrency pour vous assurer qu’un seul travail ou workflow utilisant le même groupe d’accès concurrentiel s’exécute à la fois. Un groupe d’accès concurrentiel peut être n’importe quelle chaîne ou expression. Contextes d’expression autorisés : github, inputs, vars, needs, strategy et matrix. Pour plus d’informations sur les expressions, consultez « Évaluer les expressions dans les workflows et les actions ».

Vous pouvez également spécifier concurrency au niveau du workflow. Pour plus d’informations, consultez concurrency.

Cela signifie qu’il peut y avoir au plus un travail en cours d’exécution et un travail en attente dans un groupe d’accès concurrentiel à tout moment. Quand un travail ou un workflow simultané est mis en file d’attente, si un autre travail ou workflow utilisant le même groupe d’accès concurrentiel dans le dépôt est en cours d’exécution, le travail ou le workflow en file d’attente a la valeur pending. Tout travail pending ou flux de travail existant dans le même groupe d’accès concurrentiel, s’il existe, sera annulé et le nouveau travail ou flux de travail mis en file d’attente aura lieu.

Pour annuler également un travail ou un workflow en cours d’exécution dans le même groupe d’accès concurrentiel, spécifiez cancel-in-progress: true. Pour annuler de façon conditionnelle les travaux ou les flux de travail en cours d’exécution dans le même groupe d’accès concurrentiel, vous pouvez spécifier cancel-in-progress en tant qu’expression avec l’un des contextes d’expression autorisés.

Exemple : utilisation de la concurrence et du comportement par défaut

Le comportement par défaut de GitHub Actions consiste à autoriser l'exécution simultanée de plusieurs projets ou les exécutions de flux de travail. Le mot clé concurrency vous permet de contrôler la concurrence des exécutions de flux de travail.

Par exemple, vous pouvez utiliser le mot clé concurrency immédiatement après le lieu de définition des conditions de déclenchement afin de limiter la concurrence des exécutions de l'ensemble du flux de travail pour une branche spécifique :

on:
  push:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Vous pouvez également limiter la concurrence des projets au sein d'un flux de travail en utilisant le mot-clé concurrency au niveau du projet :

on:
  push:
    branches:
      - main

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: example-group
      cancel-in-progress: true

Exemple : groupes de concurrence

Les groupes de concurrence permettent de gérer et de limiter l'exécution des flux de travail ou des projets qui partagent la même clé de concurrence.

La clé concurrency est utilisée pour regrouper des flux de travail ou des projets ensemble dans un groupe de concurrence. Lorsque vous définissez une clé concurrency, GitHub Actions garantit qu'un seul flux de travail ou projet avec cette clé s'exécute à tout moment. Si une exécution de flux de travail ou un projet est à nouveau lancé(e) avec la même clé concurrency, GitHub Actions annule tout flux de travail ou projet déjà en cours d'exécution avec cette clé. La clé concurrency peut être une chaîne codée en dur, ou il peut s'agir d'une expression dynamique qui inclut des variables de contexte.

Il est possible de définir des conditions de concurrence dans votre flux de travail afin que le flux de travail ou le projet fasse partie d'un groupe de concurrence.

En d'autres termes, lorsqu'un flux de travail ou un projet est lancé, GitHub annule tous les flux de travail ou projets déjà en cours dans le même groupe de concurrence. Cette fonction est utile dans les scénarios où vous souhaitez empêcher les exécutions parallèles pour un certain ensemble de flux de travail ou de projets, comme ceux utilisés pour les déploiements dans un environnement intermédiaire, afin d'éviter les actions susceptibles de provoquer des conflits ou de consommer plus de ressources qu'il n'est nécessaire.

Dans cet exemple, job-1 fait partie d'un groupe de concurrence nommé staging_environment. En d'autres termes, si une nouvelle exécution de job-1 est déclenchée, toutes les exécutions du même projet dans le groupe de concurrence staging_environment qui sont déjà en cours seront annulées.

jobs:
  job-1:
    runs-on: ubuntu-latest
    concurrency:
      group: staging_environment
      cancel-in-progress: true

Par ailleurs, l'utilisation d'une expression dynamique comme concurrency: ci-${{ github.ref }} dans votre flux de travail signifie que le flux de travail ou le projet fera partie d'un groupe de concurrence dont le nom ci- est suivi de la référence de la branche ou de la balise qui a déclenché le flux de travail. Dans cet exemple, si un nouvel engagement est envoyé vers la branche primaire alors qu'une exécution précédente est toujours en cours, cette dernière sera annulée et la nouvelle lancée :

on:
  push:
    branches:
      - main

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

Exemple : Utilisation de la concurrence pour annuler un travail ou une exécution en cours

Pour utiliser la concurrence afin d'annuler un projet en cours ou une exécution dans GitHub Actions, vous pouvez utiliser la clé concurrency avec l'option cancel-in-progress définie sur true :

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

Notez que dans cet exemple, sans définir un groupe de concurrence particulier, GitHub Actions annulera toute exécution en cours du projet ou du flux de travail.

Exemple : Utilisation d’une valeur de secours

Si vous créez le nom de groupe avec une propriété définie uniquement pour des événements spécifiques, vous pouvez utiliser une valeur de secours. Par exemple, github.head_ref est défini uniquement pour les événements pull_request. Si votre workflow répond à d’autres événements en plus des événements pull_request, vous devez fournir une valeur de secours pour éviter une erreur de syntaxe. Le groupe d’accès concurrentiel suivant annule les travaux ou les exécutions en cours pour les événements pull_request uniquement. Si github.head_ref n’est pas défini, le groupe d’accès concurrent utilise l’ID d’exécution, qui offre la garantie d’être à la fois unique et défini pour l’exécution.

concurrency:
  group: ${{ github.head_ref || github.run_id }}
  cancel-in-progress: true

Exemple : Annuler uniquement les travaux ou les exécutions en cours pour le workflow actuel

Si vous avez plusieurs workflows dans le même dépôt, les noms de groupes d’accès concurrentiel doivent être uniques au sein de tous les workflows pour éviter l’annulation de travaux ou d’exécutions en cours à partir d’autres workflows. Sinon, tout travail en cours ou en attente est annulé, quel que soit le workflow.

Pour annuler uniquement les exécutions en cours du même workflow, vous pouvez utiliser la propriété github.workflow afin de créer le groupe d’accès concurrentiel :

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Exemple : Annuler uniquement les travaux en cours sur des branches spécifiques

Si vous souhaitez annuler des travaux en cours sur certaines branches, mais pas sur d’autres, vous pouvez utiliser des expressions conditionnelles avec cancel-in-progress. Par exemple, vous pouvez procéder ainsi si vous souhaitez annuler les travaux en cours sur les branches de développement, mais pas sur les branches de publication.

Pour n’annuler que les exécutions en cours du même workflow lorsqu’il n’est pas exécuté sur une branche de publication, vous pouvez définir cancel-in-progress comme une expression similaire à la suivante :

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ !contains(github.ref, 'release/')}}

Dans cet exemple, plusieurs envois push vers une branche release/1.2.3 n’annulent pas les exécutions en cours. Les envois (push) vers une autre branche, par exemple main, annulent les exécutions en cours.

jobs.<job_id>.outputs

Vous pouvez utiliser jobs.<job_id>.outputs pour créer une map de sorties pour un travail. Les sorties de travail sont disponibles pour tous les travaux en aval qui dépendent de ce travail. Pour plus d’informations sur la définition des dépendances de travail, consultez jobs.<job_id>.needs.

Les sorties sont des chaînes Unicode, et leur taille maximale est de 1 Mo. La taille totale maximale de toutes les sorties d’une exécution de workflow est de 50 Mo.

Les sorties de travail contenant des expressions sont évaluées sur l’exécuteur à la fin de chaque travail. Les sorties contenant des secrets sont rédigées sur l’exécuteur et ne sont pas envoyées à GitHub Actions.

Si une production est ignorée, car elle peut contenir un secret, le message d’avertissement suivant s’affiche : « Ignorer la production {output.Key}, car elle peut contenir un secret ». Pour plus d’informations sur la gestion des secrets, consultez Exemple : masquage et transfert d’un secret entre des projets ou des flux de travail.

Pour utiliser les sorties de travail dans un travail dépendant, vous pouvez utiliser le contexte needs. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Exemple : Définition de sorties pour un travail

jobs:
  job1:
    runs-on: ubuntu-latest
    # Map a step output to a job output
    outputs:
      output1: ${{ steps.step1.outputs.test }}
      output2: ${{ steps.step2.outputs.test }}
    steps:
      - id: step1
        run: echo "test=hello" >> "$GITHUB_OUTPUT"
      - id: step2
        run: echo "test=world" >> "$GITHUB_OUTPUT"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - env:
          OUTPUT1: ${{needs.job1.outputs.output1}}
          OUTPUT2: ${{needs.job1.outputs.output2}}
        run: echo "$OUTPUT1 $OUTPUT2"

Utilisation des sorties d'un travail dans un travail matriciel

Les matrices peuvent être utilisées pour générer plusieurs sorties de noms différents. Lors de l'utilisation d'une matrice, les résultats des travaux seront combinés à partir de tous les travaux à l'intérieur de la matrice.

jobs:
  job1:
    runs-on: ubuntu-latest
    outputs:
      output_1: ${{ steps.gen_output.outputs.output_1 }}
      output_2: ${{ steps.gen_output.outputs.output_2 }}
      output_3: ${{ steps.gen_output.outputs.output_3 }}
    strategy:
      matrix:
        version: [1, 2, 3]
    steps:
      - name: Generate output
        id: gen_output
        run: |
          version="${{ matrix.version }}"
          echo "output_${version}=${version}" >> "$GITHUB_OUTPUT"
  job2:
    runs-on: ubuntu-latest
    needs: [job1]
    steps:
      # Will show
      # {
      #   "output_1": "1",
      #   "output_2": "2",
      #   "output_3": "3"
      # }
      - run: echo '${{ toJSON(needs.job1.outputs) }}'

jobs.<job_id>.env

Mappage (map) des variables qui sont disponibles pour toutes les étapes du travail. Vous pouvez définir des variables pour l’ensemble du workflow ou pour une étape individuelle. Pour plus d’informations, consultez env et jobs.<job_id>.steps[*].env.

Quand plusieurs variables d’environnement sont définies avec le même nom, GitHub utilise la variable la plus spécifique. Par exemple, une variable d’environnement définie dans une étape remplace les variables d’environnement du travail et du workflow portant le même nom, pendant l’exécution de l’étape. Une variable d’environnement définie pour un travail remplace une variable de workflow de même nom, pendant l’exécution du travail.

Exemple de jobs.<job_id>.env

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

Utilisez jobs.<job_id>.defaults pour créer un map des paramètres par défaut applicable à toutes les étapes du travail. Vous pouvez également définir des paramètres par défaut pour l’ensemble du workflow. Pour plus d’informations, consultez defaults.

Quand plusieurs paramètres par défaut sont définis avec le même nom, GitHub utilise le paramètre par défaut le plus spécifique. Par exemple, un paramètre par défaut défini dans un travail remplace un paramètre par défaut portant le même nom défini dans un workflow.

jobs.<job_id>.defaults.run

Utilisez jobs.<job_id>.defaults.run pour fournir le shell par défaut, et working-directory pour toutes les étapes run du travail.

Vous pouvez fournir des options shell et working-directory par défaut toutes les étapes run d’un travail. Vous pouvez également définir des paramètres par défaut de run pour l’ensemble du workflow. Pour plus d’informations, consultez defaults.run.

Ces éléments peuvent être remplacés aux niveaux jobs.<job_id>.defaults.run et jobs.<job_id>.steps[*].run.

Quand plusieurs paramètres par défaut sont définis avec le même nom, GitHub utilise le paramètre par défaut le plus spécifique. Par exemple, un paramètre par défaut défini dans un travail remplace un paramètre par défaut portant le même nom défini dans un workflow.

jobs.<job_id>.defaults.run.shell

Utilise shell pour définir le shell d'une étape. Ce mot clé peut référencer plusieurs contextes. Pour plus d’informations, consultez « Contextes ».

Quand plusieurs paramètres par défaut sont définis avec le même nom, GitHub utilise le paramètre par défaut le plus spécifique. Par exemple, un paramètre par défaut défini dans un travail remplace un paramètre par défaut portant le même nom défini dans un workflow.

jobs.<job_id>.defaults.run.working-directory

Utilise working-directory pour définir le répertoire de travail pour le shell d'une étape. Ce mot clé peut référencer plusieurs contextes. Pour plus d’informations, consultez « Contextes ».

Exemple : Définition d’options d’étape run par défaut pour un travail

jobs:
  job1:
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
        working-directory: ./scripts

jobs.<job_id>.steps

Un travail contient une séquence de tâches appelées « étapes » (steps). Les étapes peuvent exécuter des commandes, exécuter des tâches de configuration ou exécuter une action dans votre dépôt ou dans un dépôt public, ou une action publiée dans un registre Docker. Toutes les étapes n’exécutent pas d’actions, mais toutes les actions s’exécutent en tant qu’étape. Chaque étape s’exécute dans son propre processus dans l’environnement de l’exécuteur et a accès à l’espace de travail et au système de fichiers. Étant donné que les étapes s’exécutent dans leur propre processus, les modifications apportées aux variables d’environnement ne sont pas conservées d’une étapes à l’autre. GitHub fournit des étapes intégrées pour configurer et effectuer un travail.

GitHub affiche uniquement les 1 000 premières vérifications. Toutefois, vous pouvez exécuter un nombre illimité d’étapes tant que vous êtes dans les limites d’utilisation du workflow. Pour plus d’informations, consultez « Limites d’utilisation, facturation et administration » pour les exécuteurs hébergés par GitHub et À propos des exécuteurs auto-hébergés » pour les limites d’utilisation des exécuteurs auto-hébergés.

Exemple de jobs.<job_id>.steps

name: Greeting from Mona

on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
      - name: Print a greeting
        env:
          MY_VAR: Hi there! My name is
          FIRST_NAME: Mona
          MIDDLE_NAME: The
          LAST_NAME: Octocat
        run: |
          echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

jobs.<job_id>.steps[*].id

Identificateur unique pour l’étape. Vous pouvez utiliser l’id pour référencer l’étape dans des contextes. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

jobs.<job_id>.steps[*].if

Vous pouvez utiliser la condition if pour empêcher l’exécution d’une étape si une condition n’est pas remplie. Vous pouvez utiliser n’importe quel contexte et n’importe quelle expression pris en charge pour créer un conditionnel. Pour plus d’informations sur les contextes pris en charge dans cette clé, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Quand vous utilisez des expressions dans un conditionnel if, vous pouvez omettre la syntaxe de l’expression ${{ }} parce que GitHub Actions évalue automatiquement le conditionnel if en tant qu’expression. Toutefois, cette exception ne s’applique pas partout.

Vous devez utiliser la syntaxe d’expression ${{ }} ou l’échappement avec '', "" ou () lorsque l’expression commence par !, car ! est une notation réservée au format YAML. Par exemple :

if: ${{ ! startsWith(github.ref, 'refs/tags/') }}

Pour plus d’informations, consultez « Évaluer les expressions dans les workflows et les actions ».

Exemple : Utilisation des contextes

Cette étape s’exécute uniquement lorsque le type d’événement est pull_request et que l’action d’événement est unassigned.

steps:
  - name: My first step
    if: ${{ github.event_name == 'pull_request' && github.event.action == 'unassigned' }}
    run: echo This event is a pull request that had an assignee removed.

Exemple : Utilisation des fonctions de vérification d’état

L’étape my backup step s’exécute uniquement lorsque l’étape précédente d’un travail échoue. Pour plus d’informations, consultez « Évaluer les expressions dans les workflows et les actions ».

steps:
  - name: My first step
    uses: octo-org/action-name@main
  - name: My backup step
    if: ${{ failure() }}
    uses: actions/heroku@1.0.0

Exemple : Utilisation de secrets

Les secrets ne peuvent pas être directement référencés dans les conditions if:. Au lieu de cela, envisagez de définir des secrets en tant que variables d’environnement au niveau du travail, puis de référencer les variables d’environnement pour exécuter des étapes de manière conditionnelle dans le travail.

Si un secret n’a pas été défini, la valeur de retour d’une expression référençant le secret (comme ${{ secrets.SuperSecret }} dans l’exemple) est une chaîne vide.

name: Run a step if a secret has been set
on: push
jobs:
  my-jobname:
    runs-on: ubuntu-latest
    env:
      super_secret: ${{ secrets.SuperSecret }}
    steps:
      - if: ${{ env.super_secret != '' }}
        run: echo 'This step will only run if the secret has a value set.'
      - if: ${{ env.super_secret == '' }}
        run: echo 'This step will only run if the secret does not have a value set.'

Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow » et « Utilisation de secrets dans GitHub Actions ».

jobs.<job_id>.steps[*].name

Nom de votre étape à afficher sur GitHub.

jobs.<job_id>.steps[*].uses

Sélectionne une action à exécuter dans le cadre d’une étape de votre travail. Une action est une unité de code réutilisable. Vous pouvez utiliser une action définie dans le même dépôt que le workflow, dans un dépôt public ou dans une image conteneur Docker publiée.

Nous vous recommandons vivement d’inclure la version de l’action que vous utilisez en spécifiant une étiquette Git ref, SHA ou Docker. Si vous ne spécifiez pas de version, cela peut arrêter vos workflows ou provoquer un comportement inattendu lorsque le propriétaire de l’action publie une mise à jour.

• L’utilisation du SHA de commit d’une version d’action publiée est la solution la plus sûre en termes de stabilité et de sécurité.
• Si l’action publie des étiquettes de version principale, vous devez vous attendre à recevoir des correctifs critiques et des correctifs de sécurité qui conserveront la compatibilité. Notez que ce comportement est à la discrétion de l’auteur de l’action.
• L’utilisation de la branche par défaut d’une action peut être pratique. Toutefois, si un utilisateur publie une nouvelle version majeure avec un changement cassant, votre workflow peut s’arrêter.

Certaines actions nécessitent des entrées que vous devez définir à l’aide du mot clé with. Examinez le fichier README de l’action pour déterminer les entrées nécessaires.

Les actions sont des fichiers JavaScript ou des conteneurs Docker. Si l’action que vous utilisez est un conteneur Docker, vous devez exécuter le travail dans un environnement Linux. Pour plus d’informations, consultez la page runs-on.

Exemple : Utilisation d’actions avec versions gérées

steps:
  # Reference a specific commit
  - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
  # Reference the major version of a release
  - uses: actions/checkout@v4
  # Reference a specific version
  - uses: actions/checkout@v4.2.0
  # Reference a branch
  - uses: actions/checkout@main

Exemple : Utilisation d’une action publique

{owner}/{repo}@{ref}

Vous pouvez spécifier une branche, une référence ou un SHA dans un dépôt GitHub public.

jobs:
  my_first_job:
    steps:
      - name: My first step
        # Uses the default branch of a public repository
        uses: actions/heroku@main
      - name: My second step
        # Uses a specific version tag of a public repository
        uses: actions/aws@v2.0.1

Exemple : Utilisation d’une action publique dans un sous-répertoire

{owner}/{repo}/{path}@{ref}

Sous-répertoire dans un dépôt GitHub public sur une branche, une référence ou un SHA spécifique.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/aws/ec2@main

Exemple : Utilisation d’une action dans le même dépôt que le workflow

./path/to/dir

Chemin du répertoire qui contient l’action dans le dépôt de votre workflow. Vous devez valider votre dépôt avant d’utiliser l’action.

Exemple de structure de fichier de dépôt :

|-- hello-world (repository)
|   |__ .github
|       └── workflows
|           └── my-first-workflow.yml
|       └── actions
|           |__ hello-world-action
|               └── action.yml

Le chemin d’accès relatif (./) par rapport au répertoire de travail par défaut (github.workspace, $GITHUB_WORKSPACE). Si l’action extrait le référentiel d’un emplacement différent du flux de travail, le chemin d’accès relatif utilisé pour les actions locales doit être mis à jour.

Exemple de fichier de workflow :

jobs:
  my_first_job:
    runs-on: ubuntu-latest
    steps:
      # This step checks out a copy of your repository.
      - name: My first step - check out repository
        uses: actions/checkout@v4
      # This step references the directory that contains the action.
      - name: Use local hello-world-action
        uses: ./.github/actions/hello-world-action

Exemple : Utilisation d’une action de Docker Hub

docker://{image}:{tag}

Image Docker publiée sur Docker Hub.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://alpine:3.8

Exemple : Utilisation d’une action de registre public Docker

docker://{host}/{image}:{tag}

Image Docker dans un registre public. Cet exemple utilise Google Container Registry à l’adresse gcr.io.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: docker://gcr.io/cloud-builders/gradle

Exemple : Utilisation d’une action à l’intérieur d’un autre dépôt privé que le workflow

Votre workflow doit valider le dépôt privé et référencer l’action localement. Générez un personal access token et ajoutez le jeton en tant que secret. Pour plus d’informations, consultez « Gestion de vos jetons d'accès personnels » et « Utilisation de secrets dans GitHub Actions ».

Remplacez PERSONAL_ACCESS_TOKEN dans l’exemple par le nom de votre secret.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          repository: octocat/my-private-repo
          ref: v1.0
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: ./.github/actions/my-private-repo
      - name: Run my action
        uses: ./.github/actions/my-private-repo/my-action

Vous pouvez également utiliser une GitHub App au lieu d’un personal access token pour vous assurer que votre workflow continue de s’exécuter même si le propriétaire du personal access token quitte l’entreprise. Pour plus d’informations, consultez « Effectuer des requêtes d’API authentifiées avec une application GitHub dans un workflow GitHub Actions ».

jobs.<job_id>.steps[*].run

Exécute des programmes en ligne de commande qui ne dépassent pas 21 000 caractères à l’aide de l’interpréteur de commandes du système d’exploitation. Si vous ne fournissez pas d’élément name, le nom de l’étape est défini par défaut sur le texte spécifié dans la commande run.

Par défaut, les commandes s’exécutent à l’aide d’interpréteurs de commandes sans connexion. Vous pouvez choisir un autre interpréteur de commandes et personnaliser l’interpréteur de commandes utilisé pour exécuter des commandes. Pour plus d’informations, consultez jobs.<job_id>.steps[*].shell.

Chaque mot clé run représente un nouveau processus et un nouvel interpréteur de commandes dans l’environnement de l’exécuteur. Lorsque vous fournissez des commandes qui s’étendent sur plusieurs lignes, chaque ligne s’exécute dans le même interpréteur de commandes. Par exemple :

• Commande sur une seule ligne :

  - name: Install Dependencies
    run: npm install
  

• Commande sur plusieurs lignes :

  - name: Clean install dependencies and build
    run: |
      npm ci
      npm run build
  

jobs.<job_id>.steps[*].working-directory

À l’aide du mot clé working-directory, vous pouvez spécifier le répertoire de travail d’où exécuter la commande.

- name: Clean temp directory
  run: rm -rf *
  working-directory: ./temp

Vous pouvez également spécifier un répertoire de travail par défaut pour toutes les étapes run d'un projet ou pour toutes les étapes run de l'ensemble du flux de travail. Pour en savoir plus, consultez « defaults.run.working-directory » et « jobs.<job_id>.defaults.run.working-directory ».

Vous pouvez également utiliser une étape run pour exécuter un script. Pour plus d’informations, consultez « Ajout de scripts à votre workflow ».

jobs.<job_id>.steps[*].shell

Vous pouvez remplacer les paramètres du shell par défaut dans le système d'exploitation de l'exécuteur et les paramètres par défaut du travail à l'aide du mot-clé shell. Vous pouvez utiliser des mots clés shell intégrés ou définir un ensemble personnalisé d’options d’interpréteur de commandes. La commande d’interpréteur de commandes exécutée en interne exécute un fichier temporaire qui contient les commandes spécifiées dans le mot clé run.

Vous pouvez également spécifier un shell par défaut pour toutes les étapes run d'un projet ou pour toutes les étapes run de l'ensemble du flux de travail. Pour en savoir plus, consultez « defaults.run.shell » et « jobs.<job_id>.defaults.run.shell ».

Exemple : Exécution d’une commande à l’aide de Bash

steps:
  - name: Display the path
    shell: bash
    run: echo $PATH

Exemple : Exécution d’une commande à l’aide de Windows cmd

steps:
  - name: Display the path
    shell: cmd
    run: echo %PATH%

Exemple : Exécution d’une commande à l’aide de PowerShell Core

steps:
  - name: Display the path
    shell: pwsh
    run: echo ${env:PATH}

Exemple : Utilisation de PowerShell Desktop pour exécuter une commande

steps:
  - name: Display the path
    shell: powershell
    run: echo ${env:PATH}

Exemple : Exécution d’un script Python inline

steps:
  - name: Display the path
    shell: python
    run: |
      import os
      print(os.environ['PATH'])

Interpréteur de commandes personnalisé

Vous pouvez définir la valeur shell sur une chaîne de modèle à l’aide de command [options] {0} [more_options]. GitHub interprète le premier mot délimité par des espaces blancs de la chaîne comme la commande, et insère le nom de fichier pour le script temporaire à l’emplacement {0}.

Par exemple :

steps:
  - name: Display the environment variables and their values
    shell: perl {0}
    run: |
      print %ENV

La commande utilisée, perl dans cet exemple, doit être installée sur l’exécuteur.

Codes de sortie et préférence d’action en cas d’erreur

Pour les mots clés d’interpréteur de commandes intégrés, nous fournissons les valeurs par défaut suivantes qui sont exécutées par les exécuteurs hébergés par GitHub. Vous devez utiliser ces instructions lors de l’exécution de scripts de l’interpréteur de commandes.

• bash/sh :

  • Par défaut, le comportement spécifique au mode Fail-fast est appliqué en utilisant set -e tant pour sh, que d’autant pour bash. Lorsque shell: bash est spécifié, -o pipefail est également appliqué pour mettre en œuvre la sortie anticipée des pipelines qui génèrent un état de sortie différent de zéro.
  • Vous pouvez prendre le contrôle total des paramètres de l’interpréteur de commandes en fournissant une chaîne de modèle aux options de l’interpréteur de commandes. Par exemple : bash {0}.
  • Les interpréteurs de commandes de type sh se terminent par le code de sortie de la dernière commande exécutée dans un script, ce qui est également le comportement par défaut pour les actions. L’exécuteur signale l’état de l’étape en tant qu’échec/réussite en fonction de ce code de sortie.

• powershell/pwsh

  • Comportement Fail-fast lorsque cela est possible. Pour l’interpréteur de commandes intégré pwsh et powershell, nous allons ajouter $ErrorActionPreference = 'stop' au contenu du script.
  • Nous ajoutons if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } aux scripts PowerShell afin que les états d’action reflètent le dernier code de sortie du script.
  • Les utilisateurs peuvent toujours choisir de ne pas utiliser l’interpréteur de commandes intégré et de fournir une option d’interpréteur de commandes personnalisée comme pwsh -File {0} ou powershell -Command "& '{0}'", selon les besoins.

• cmd

  • Il semble qu’il n’existe pas de moyen d’adopter entièrement un comportement Fail-fast autre que l’écriture de votre script pour vérifier chaque code d’erreur et répondre en conséquence. Étant donné que nous ne pouvons en fait pas fournir ce comportement par défaut, vous devez écrire ce comportement dans votre script.
  • cmd.exe s’arrête avec le niveau d’erreur du dernier programme qu’il a exécuté, et retourne le code d’erreur à l’exécuteur. Ce comportement est cohérent en interne avec le comportement par défaut précédent de sh et de pwsh, et c’est la valeur par défaut de cmd.exe. Ce comportement reste donc intact.

jobs.<job_id>.steps[*].with

Mappage (map) des paramètres d’entrée définis par l’action. Chaque paramètre d’entrée est une paire clé/valeur. Les paramètres d’entrée sont définis en tant que variables d’environnement. La variable est dotée du préfixe INPUT_ et est convertie en majuscules.

Les paramètres d’entrée définis pour un conteneur Docker doivent utiliser args. Pour plus d’informations, consultez « jobs.<job_id>.steps[*].with.args ».

Exemple de jobs.<job_id>.steps[*].with

Définit les trois paramètres d’entrée (first_name, middle_name et last_name) définis par l’action hello_world. Ces variables d’entrée seront accessibles à l’action hello-world en tant que variables d’environnement INPUT_FIRST_NAME, INPUT_MIDDLE_NAME et INPUT_LAST_NAME.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/hello_world@main
        with:
          first_name: Mona
          middle_name: The
          last_name: Octocat

jobs.<job_id>.steps[*].with.args

Une valeur string définit les entrées d’un conteneur Docker. GitHub passe args au ENTRYPOINT du conteneur quand ce dernier démarre. Un array of strings n’est pas pris en charge par ce paramètre. Un argument unique qui inclut des espaces doit être entouré de guillemets doubles "".

Exemple de jobs.<job_id>.steps[*].with.args

steps:
  - name: Explain why this job ran
    uses: octo-org/action-name@main
    with:
      entrypoint: /bin/echo
      args: The ${{ github.event_name }} event triggered this step.

Les valeurs args sont utilisées à la place de l’instruction CMD dans un Dockerfile. Si vous utilisez CMD dans votre Dockerfile, utilisez les instructions classées par ordre de préférence :

1. Documentez les arguments requis dans le fichier README de l’action et omettez-les de l’instruction CMD.
2. Utilisez les valeurs par défaut qui autorisent l’utilisation de l’action sans spécifier aucune valeur args.
3. Si l’action expose un indicateur --help, ou quelque chose de similaire, utilisez-le comme valeur par défaut pour rendre votre action auto-documentée.

jobs.<job_id>.steps[*].with.entrypoint

Remplace la valeur ENTRYPOINT Docker dans le Dockerfile, ou la définit si aucune n’est encore spécifiée. Contrairement à l’instruction Docker ENTRYPOINT qui a un interpréteur de commandes et le format exec, le mot clé entrypoint accepte une seule chaîne définissant l’exécutable à exécuter.

Exemple de jobs.<job_id>.steps[*].with.entrypoint

steps:
  - name: Run a custom command
    uses: octo-org/action-name@main
    with:
      entrypoint: /a/different/executable

Le mot clé entrypoint est destiné à être utilisé avec des actions de conteneur Docker, mais vous pouvez également l’utiliser avec des actions JavaScript qui ne définissent aucune entrée.

jobs.<job_id>.steps[*].env

Définit des variables pour les étapes à utiliser dans l’environnement de l’exécuteur. Vous pouvez également définir des variables pour l’ensemble du workflow ou pour un travail. Pour plus d’informations, consultez env et jobs.<job_id>.env.

Quand plusieurs variables d’environnement sont définies avec le même nom, GitHub utilise la variable la plus spécifique. Par exemple, une variable d’environnement définie dans une étape remplace les variables d’environnement du travail et du workflow portant le même nom, pendant l’exécution de l’étape. Une variable d’environnement définie pour un travail remplace une variable de workflow de même nom, pendant l’exécution du travail.

Les actions publiques peuvent spécifier les variables attendues dans le fichier README. Si vous définissez un secret ou une valeur sensible, comme un mot de passe ou un jeton, vous devez définir des secrets à l’aide du contexte secrets. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Exemple de jobs.<job_id>.steps[*].env

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      FIRST_NAME: Mona
      LAST_NAME: Octocat

jobs.<job_id>.steps[*].continue-on-error

Empêche que l’échec d’une étape fasse échouer un travail. Définissez la valeur true pour permettre à un travail de réussir en cas d’échec de cette étape.

jobs.<job_id>.steps[*].timeout-minutes

Nombre maximal de minutes pour exécuter l’étape avant l’arrêt du processus.

Les valeurs fractionnaires ne sont pas prises en charge. timeout-minutes doit être un entier positif.

jobs.<job_id>.timeout-minutes

Nombre maximal de minutes pour permettre à un travail de s’exécuter avant que GitHub l’annule automatiquement. Valeur par défaut : 360

Si le délai d’expiration dépasse le délai d’exécution du travail pour l’exécuteur, le travail est annulé lorsque le délai d’exécution est écoulé à la place. Pour plus d’informations sur les limites de temps d’exécution des tâches, consultez « Limites d’utilisation, facturation et administration » pour les exécuteurs hébergés par GitHub et À propos des exécuteurs auto-hébergés » pour les limites d’utilisation des exécuteurs autohébergés.

jobs.<job_id>.strategy

Utilisez jobs.<job_id>.strategy pour utiliser une stratégie de matrice pour vos travaux. Une stratégie de matrice vous permet d’utiliser des variables dans une définition de travail unique pour créer automatiquement plusieurs exécutions de travaux basées sur les combinaisons des variables. Par exemple, vous pouvez utiliser une stratégie de matrice pour tester votre code dans plusieurs versions d’un langage ou sur plusieurs systèmes d’exploitation. Pour plus d’informations, consultez « Exécution de variantes de tâches dans un workflow ».

jobs.<job_id>.strategy.matrix

Utilisez jobs.<job_id>.strategy.matrix pour définir une matrice de différentes configurations de travail. Dans votre matrice, définissez une ou plusieurs variables suivies d’un tableau de valeurs. Par exemple, la matrice suivante a une variable appelée version avec la valeur [10, 12, 14], et une variable appelée os avec la valeur [ubuntu-latest, windows-latest] :

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

Un travail s’exécute pour chaque combinaison possible des variables. Dans cet exemple, le workflow exécute six travaux, un pour chaque combinaison des variables os et version.

Par défaut, GitHub Enterprise Server optimise le nombre de travaux exécutés en parallèle en fonction de la disponibilité des exécuteurs. L’ordre des variables dans la matrice détermine l’ordre dans lequel les travaux sont créés. La première variable que vous définissez est le premier travail créé dans votre exécution de workflow. Par exemple, la matrice ci-dessus crée les travaux dans l’ordre suivant :

• {version: 10, os: ubuntu-latest}
• {version: 10, os: windows-latest}
• {version: 12, os: ubuntu-latest}
• {version: 12, os: windows-latest}
• {version: 14, os: ubuntu-latest}
• {version: 14, os: windows-latest}

Une matrice génère au maximum 256 travaux par exécution de workflow. Cette limite s’applique aux exécuteurs hébergés sur GitHub Enterprise Server et à ceux qui sont autohébergés.

Les variables que vous définissez deviennent des propriétés dans le contexte matrix. Vous pouvez référencer la propriété dans d’autres zones de votre fichier de workflow. Dans cet exemple, vous pouvez utiliser matrix.version et matrix.os pour accéder aux valeurs actuelles de version et os utilisées par le travail. Pour plus d’informations, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Exemple : Utilisation d’une matrice à une seule dimension

Vous pouvez spécifier une seule variable pour créer une matrice unidimensionnelle.

Par exemple, le workflow suivant définit la variable version avec les valeurs [10, 12, 14]. Le workflow exécute trois travaux, un pour chaque valeur de la variable. Chaque travail accède à la valeur version via le contexte matrix.version, et passe la valeur en tant que node-version à l’action actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        version: [10, 12, 14]
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

Exemple : Utilisation d’une matrice à plusieurs dimensions

Vous pouvez spécifier plusieurs variables pour créer une matrice multidimensionnelle. Un travail s’exécute pour chaque combinaison possible des variables.

Par exemple, le workflow suivant spécifie deux variables :

• Deux systèmes d’exploitation spécifiés dans la variable os
• Trois versions de Node.js spécifiées dans la variable version

Le workflow exécute six travaux, un pour chaque combinaison des variables os et version. Chaque travail affecte la valeur runs-on à la valeur os actuelle, et passe la valeur version actuelle à l’action actions/setup-node.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [ubuntu-22.04, ubuntu-20.04]
        version: [10, 12, 14]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

Une configuration de variable dans une matrice peut être un array de objects.

matrix:
  os:
    - ubuntu-latest
    - macos-latest
  node:
    - version: 14
    - version: 20
      env: NODE_OPTIONS=--openssl-legacy-provider

Cette matrice produit quatre travaux avec des contextes correspondants.

- matrix.os: ubuntu-latest
  matrix.node.version: 14
- matrix.os: ubuntu-latest
  matrix.node.version: 20
  matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider
- matrix.os: macos-latest
  matrix.node.version: 14
- matrix.os: macos-latest
  matrix.node.version: 20
  matrix.node.env: NODE_OPTIONS=--openssl-legacy-provider

Exemple : Utilisation de contextes pour créer des matrices

Vous pouvez utiliser des contextes pour créer des matrices. Pour plus d’informations sur les contextes, consultez « Accès à des informations contextuelles sur l’exécution d’un workflow ».

Par exemple, le workflow suivant se déclenche sur l’événement repository_dispatch et utilise les informations de la charge utile de l’événement pour générer la matrice. Lorsqu’un événement de répartition de référentiel est créé avec une charge utile comme celle ci-dessous, la variable de matrice version a la valeur [12, 14, 16]. Pour plus d’informations sur le déclencheur repository_dispatch, consultez « Événements qui déclenchent des flux de travail ».

{
  "event_type": "test",
  "client_payload": {
    "versions": [12, 14, 16]
  }
}

on:
  repository_dispatch:
    types:
      - test
 
jobs:
  example_matrix:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ github.event.client_payload.versions }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.version }}

jobs.<job_id>.strategy.matrix.include

Utilisez jobs.<job_id>.strategy.matrix.include pour développer des configurations de matrice existantes ou ajouter de nouvelles configurations. La valeur de include est une liste d’objets.

Pour chaque objet de la liste include, les paires clé:valeur dans l’objet sont ajoutées à chacune des combinaisons de matrices si aucune des paires clé:valeur ne remplace les valeurs de matrice d’origine. Si l’objet ne peut pas être ajouté à l’une des combinaisons de matrices, une nouvelle combinaison de matrices est créée à la place. Notez que les valeurs de matrice d’origine ne seront pas remplacées, mais que les valeurs de matrice ajoutées peuvent être remplacées.

Par exemple, cette matrice :

strategy:
  matrix:
    fruit: [apple, pear]
    animal: [cat, dog]
    include:
      - color: green
      - color: pink
        animal: cat
      - fruit: apple
        shape: circle
      - fruit: banana
      - fruit: banana
        animal: cat

entraîne six travaux avec les combinaisons de matrices suivantes :

• {fruit: apple, animal: cat, color: pink, shape: circle}
• {fruit: apple, animal: dog, color: green, shape: circle}
• {fruit: pear, animal: cat, color: pink}
• {fruit: pear, animal: dog, color: green}
• {fruit: banana}
• {fruit: banana, animal: cat}

en suivant cette logique :

• {color: green} est ajouté à toutes les combinaisons de matrices d’origine, car il peut être ajouté sans remplacer aucune partie des combinaisons d’origine.
• {color: pink, animal: cat} ajoute color:pink uniquement aux combinaisons de matrices d’origine qui incluent animal: cat. Cela remplace le color: green qui a été ajouté par l’entrée include précédente.
• {fruit: apple, shape: circle} ajoute shape: circle uniquement aux combinaisons de matrices d’origine qui incluent fruit: apple.
• {fruit: banana} ne peut pas être ajouté à une combinaison de matrices d’origine sans remplacer une valeur. Il est donc ajouté en tant que combinaison de matrices supplémentaire.
• {fruit: banana, animal: cat} ne peut pas être ajouté à une combinaison de matrices d’origine sans remplacer une valeur. Il est donc ajouté en tant que combinaison de matrices supplémentaire. Cela ne l’ajoute pas à la combinaison de matrices {fruit: banana}, car cette combinaison n’était pas l’une des combinaisons de matrices d’origine.

Exemple : Développement de configurations

Par exemple, le workflow suivant exécute quatre tâches, un pour chaque combinaison de os et node. Lorsque le travail pour la valeur os de windows-latest et la valeur node de 16 s’exécute, une variable supplémentaire appelée npm avec la valeur 6 sera incluse dans le travail.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [windows-latest, ubuntu-latest]
        node: [14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - if: ${{ matrix.npm }}
        run: npm install -g npm@${{ matrix.npm }}
      - run: npm --version

Exemple : Ajout de configurations

Par exemple, cette matrice exécutera 10 travaux, un pour chaque combinaison de os et version dans la matrice, plus un travail pour la valeur os de windows-latest et la valeur version de 17.

jobs:
  example_matrix:
    strategy:
      matrix:
        os: [macos-latest, windows-latest, ubuntu-latest]
        version: [12, 14, 16]
        include:
          - os: windows-latest
            version: 17

Si vous ne spécifiez aucune variable de matrice, toutes les configurations sous include sont exécutées. Par exemple, le workflow suivant exécuterait deux travaux, un pour chaque entrée include. Cela vous permet de tirer parti de la stratégie de matrice sans avoir une matrice entièrement remplie.

jobs:
  includes_only:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - site: "production"
            datacenter: "site-a"
          - site: "staging"
            datacenter: "site-b"

jobs.<job_id>.strategy.matrix.exclude

Pour supprimer des configurations spécifiques définies dans la matrice, utilisez jobs.<job_id>.strategy.matrix.exclude. Une configuration exclue a seulement besoin d’être une correspondance partielle pour être exclue. Par exemple, le workflow suivant exécute neuf travaux : un travail pour chacune des 12 configurations, moins un travail exclu qui correspond à {os: macos-latest, version: 12, environment: production}, et les deux travaux exclus qui correspondent à {os: windows-latest, version: 16}.

strategy:
  matrix:
    os: [macos-latest, windows-latest]
    version: [12, 14, 16]
    environment: [staging, production]
    exclude:
      - os: macos-latest
        version: 12
        environment: production
      - os: windows-latest
        version: 16
runs-on: ${{ matrix.os }}

jobs.<job_id>.strategy.fail-fast

Vous pouvez contrôler la façon dont les échecs de travaux sont gérés avec jobs.<job_id>.strategy.fail-fast et jobs.<job_id>.continue-on-error.

jobs.<job_id>.strategy.fail-fast s’applique à l’ensemble de la matrice. Si jobs.<job_id>.strategy.fail-fast est défini sur true, ou son expression aboutit à true, GitHub Enterprise Server annule tous les travaux en cours et en file d’attente dans la matrice en cas d’échec d’un des travaux de la matrice. Cette propriété a la valeur par défaut true.

jobs.<job_id>.continue-on-error s’applique à un seul travail. Si jobs.<job_id>.continue-on-error a la valeur true, les autres travaux de la matrice continuent de s’exécuter même en cas d’échec du travail avec jobs.<job_id>.continue-on-error: true.

Vous pouvez utiliser jobs.<job_id>.strategy.fail-fast et jobs.<job_id>.continue-on-error ensemble. Par exemple, le workflow suivant démarre quatre travaux. Pour chaque travail, continue-on-error est déterminé par la valeur de matrix.experimental. En cas d’échec de l’un des travaux avec continue-on-error: false, tous les travaux en cours ou en file d’attente sont annulés. En cas d’échec du travail avec continue-on-error: true, les autres travaux ne sont pas affectés.

jobs:
  test:
    runs-on: ubuntu-latest
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: true
      matrix:
        version: [6, 7, 8]
        experimental: [false]
        include:
          - version: 9
            experimental: true

jobs.<job_id>.strategy.max-parallel

Par défaut, GitHub Enterprise Server optimise le nombre de travaux exécutés en parallèle en fonction de la disponibilité de l’exécuteur. Pour définir le nombre maximal de travaux pouvant s’exécuter simultanément lors de l’utilisation d’une stratégie de travail matrix, utilisez jobs.<job_id>.strategy.max-parallel.

Par exemple, le workflow suivant exécute au maximum de deux travaux à la fois, même s’il existe des exécuteurs disponibles pour exécuter les six travaux en même temps.

jobs:
  example_matrix:
    strategy:
      max-parallel: 2
      matrix:
        version: [10, 12, 14]
        os: [ubuntu-latest, windows-latest]

jobs.<job_id>.continue-on-error

Empêche que l’échec d’un travail fasse échouer une exécution de workflow. Définissez la valeur true pour permettre à un workflow de réussir en cas d’échec de ce travail.

Exemple : Empêcher un travail de matrice défaillant spécifique de faire échouer une exécution de workflow

Vous pouvez autoriser l’échec de travaux spécifiques d’une matrice de travaux sans faire échouer l’exécution du workflow. Par exemple, si vous souhaitiez autoriser uniquement un travail expérimental avec node défini sur 15 à échouer sans faire échouer l’exécution du workflow.

runs-on: ${{ matrix.os }}
continue-on-error: ${{ matrix.experimental }}
strategy:
  fail-fast: false
  matrix:
    node: [13, 14]
    os: [macos-latest, ubuntu-latest]
    experimental: [false]
    include:
      - node: 15
        os: ubuntu-latest
        experimental: true

jobs.<job_id>.container

Utilisez jobs.<job_id>.container pour créer un conteneur permettant d’exécuter les étapes d’un travail qui ne spécifient pas encore de conteneur. Si vous avez des étapes qui utilisent à la fois des actions de script et des actions de conteneur, les actions de conteneur s’exécutent en tant que conteneurs frères sur le même réseau avec les mêmes montages de volume.

Si vous ne définissez pas de container, toutes les étapes s’exécutent directement sur l’hôte spécifié par runs-on, sauf si une étape fait référence à une action configurée pour s’exécuter dans un conteneur.

Exemple : Exécution d’un travail dans un conteneur

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:18
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:18
      env:
        NODE_ENV: development
      ports:
        - 80
      volumes:
        - my_docker_volume:/volume_mount
      options: --cpus 1
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

Quand vous spécifiez uniquement une image conteneur, vous pouvez omettre le mot clé image.

jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container: node:18

jobs.<job_id>.container.image

Utilisez jobs.<job_id>.container.image pour définir l’image Docker à utiliser en tant que conteneur afin d’exécuter l’action. La valeur peut être le nom de l’image Docker Hub ou un nom de registre.

jobs.<job_id>.container.credentials

Si le registre de conteneurs de l’image nécessite une authentification pour tirer l’image, vous pouvez utiliser jobs.<job_id>.container.credentials pour définir un map de username et de password. Les informations d’identification correspondent aux mêmes valeurs que celles que vous fournissez à la commande docker login.

Exemple : Définition des informations d’identification d’un registre de conteneurs

container:
  image: ghcr.io/owner/image
  credentials:
     username: ${{ github.actor }}
     password: ${{ secrets.github_token }}

jobs.<job_id>.container.env

Utilisez jobs.<job_id>.container.env pour définir un map de variables d’environnement dans le conteneur.

jobs.<job_id>.container.ports

Utilisez jobs.<job_id>.container.ports pour définir un array de ports à exposer sur le conteneur.

jobs.<job_id>.container.volumes

Utilisez jobs.<job_id>.container.volumes pour définir un array de volumes à utiliser par le conteneur. Vous pouvez utiliser des volumes pour partager des données entre des services ou d’autres étapes d’un travail. Vous pouvez spécifier des volumes Docker nommés, des volumes Docker anonymes ou des montages de liaisons sur l’hôte.

Pour spécifier un volume, vous spécifiez le chemin source et le chemin de destination :

<source>:<destinationPath>.

La valeur <source> est un nom de volume ou un chemin absolu sur la machine hôte et <destinationPath> est un chemin absolu dans le conteneur.

Exemple : Montage de volumes dans un conteneur

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.container.options

Utilisez jobs.<job_id>.container.options pour configurer des options supplémentaires de ressources de conteneur Docker. Pour obtenir la liste des options, consultez « Options docker create ».

jobs.<job_id>.services

Utilisé pour héberger des conteneurs de service pour un travail dans un workflow. Les conteneurs de service sont utiles pour créer des bases de données ou des services de cache comme Redis. L’exécuteur crée automatiquement un réseau Docker et gère le cycle de vie des conteneurs de service.

Si vous configurez votre travail pour qu’il s’exécute dans un conteneur ou que votre étape utilise des actions de conteneur, vous n’avez pas besoin de mapper les ports pour accéder au service ou à l’action. Docker expose automatiquement tous les ports entre les conteneurs se trouvant sur le même réseau de pont défini par l’utilisateur Docker. Vous pouvez référencer directement le conteneur de service par son nom d’hôte. Le nom d’hôte est automatiquement mappé au nom d’étiquette que vous configurez pour le service dans le workflow.

Si vous configurez le travail pour qu’il s’exécute directement sur la machine de l’exécuteur et que votre étape n’utilise pas d’action de conteneur, vous devez mapper tous les ports de conteneur de service Docker requis à l’hôte Docker (la machine de l’exécuteur). Vous pouvez accéder au conteneur de service à l’aide de localhost et du port mappé.

Pour plus d’informations sur les différences entre les conteneurs de service réseau, consultez « À propos des conteneurs de service ».

Exemple : Utilisation de localhost

Cet exemple crée deux services : nginx et redis. Lorsque vous spécifiez le port du conteneur, mais pas le port de l’hôte, le port du conteneur est attribué de manière aléatoire à un port libre sur l’hôte. GitHub définit le port d’hôte affecté dans le contexte ${{job.services.<service_name>.ports}}. Dans cet exemple, vous pouvez accéder aux ports d’hôte de service à l’aide des contextes ${{ job.services.nginx.ports['80'] }} et ${{ job.services.redis.ports['6379'] }}.

services:
  nginx:
    image: nginx
    # Map port 8080 on the Docker host to port 80 on the nginx container
    ports:
      - 8080:80
  redis:
    image: redis
    # Map random free TCP port on Docker host to port 6379 on redis container
    ports:
      - 6379/tcp
steps:
  - run: |
      echo "Redis available on 127.0.0.1:${{ job.services.redis.ports['6379'] }}"
      echo "Nginx available on 127.0.0.1:${{ job.services.nginx.ports['80'] }}"

jobs.<job_id>.services.<service_id>.image

Image Docker à utiliser comme conteneur de service pour exécuter l’action. La valeur peut être le nom de l’image Docker Hub ou un nom de registre.

Si jobs.<job_id>.services.<service_id>.image est une chaîne vide, le service ne démarre pas. Vous pouvez l’utiliser pour configurer des services conditionnels, comme dans l’exemple suivant.

services:
  nginx:
    image: ${{ options.nginx == true && 'nginx' || '' }}

jobs.<job_id>.services.<service_id>.credentials

Si le registre de conteneurs de l’image nécessite une authentification pour tirer l’image, vous pouvez utiliser jobs.<job_id>.container.credentials pour définir un map de username et de password. Les informations d’identification correspondent aux mêmes valeurs que celles que vous fournissez à la commande docker login.

Exemple de jobs.<job_id>.services.<service_id>.credentials

services:
  myservice1:
    image: ghcr.io/owner/myservice1
    credentials:
      username: ${{ github.actor }}
      password: ${{ secrets.github_token }}
  myservice2:
    image: dockerhub_org/myservice2
    credentials:
      username: ${{ secrets.DOCKER_USER }}
      password: ${{ secrets.DOCKER_PASSWORD }}

jobs.<job_id>.services.<service_id>.env

Définit un mappage (map) de variables d’environnement dans le conteneur de service.

jobs.<job_id>.services.<service_id>.ports

Définit un tableau (array) de ports à exposer sur le conteneur de service.

jobs.<job_id>.services.<service_id>.volumes

Définit un tableau (array) de volumes pour le conteneur de service à utiliser. Vous pouvez utiliser des volumes pour partager des données entre des services ou d’autres étapes d’un travail. Vous pouvez spécifier des volumes Docker nommés, des volumes Docker anonymes ou des montages de liaisons sur l’hôte.

Pour spécifier un volume, vous spécifiez le chemin source et le chemin de destination :

<source>:<destinationPath>.

La valeur <source> est un nom de volume ou un chemin absolu sur la machine hôte et <destinationPath> est un chemin absolu dans le conteneur.

Exemple de jobs.<job_id>.services.<service_id>.volumes

volumes:
  - my_docker_volume:/volume_mount
  - /data/my_data
  - /source/directory:/destination/directory

jobs.<job_id>.services.<service_id>.options

Options de ressources de conteneur Docker supplémentaires. Pour obtenir la liste des options, consultez « Options docker create ».

jobs.<job_id>.uses

Emplacement et version d’un fichier de workflow réutilisable à exécuter en tant que travail. Utilisez l’une des syntaxes suivantes :

• {owner}/{repo}/.github/workflows/{filename}@{ref} pour les flux de travail réutilisables dans les dépôts publics, internes et privés.
• ./.github/workflows/{filename} pour des workflows réutilisables dans le même dépôt.

Dans la première options, {ref} peut être un SHA, une étiquette de mise en production ou un nom de branche. Si une balise de mise en production et une branche portent le même nom, la balise de mise en production est prioritaire sur le nom de la branche. L’utilisation du SHA de validation est l’option la plus sûre pour la stabilité et la sécurité. Pour plus d’informations, consultez « Durcissement de la sécurité pour GitHub Actions ».

Si vous utilisez la deuxième option de syntaxe (sans {owner}/{repo} et @{ref}), le workflow appelé provient du même commit que le workflow appelant. Les préfixes ref tels que refs/heads et refs/tags ne sont pas autorisés. Vous ne pouvez pas utiliser de contextes ou d’expressions dans ce mot clé.

Exemple de jobs.<job_id>.uses

jobs:
  call-workflow-1-in-local-repo:
    uses: octo-org/this-repo/.github/workflows/workflow-1.yml@172239021f7ba04fe7327647b213799853a9eb89
  call-workflow-2-in-local-repo:
    uses: ./.github/workflows/workflow-2.yml
  call-workflow-in-another-repo:
    uses: octo-org/another-repo/.github/workflows/workflow.yml@v1

Pour plus d’informations, consultez « Réutilisation des workflows ».

jobs.<job_id>.with

Lorsqu’un travail est utilisé pour appeler un workflow réutilisable, vous pouvez utiliser with pour fournir un mappage d’entrées qui sont passées au workflow appelé.

Toutes les entrées que vous passez doivent correspondre aux spécifications d’entrée définies dans le workflow appelé.

Contrairement à jobs.<job_id>.steps[*].with, les entrées que vous passez avec jobs.<job_id>.with sont non disponibles en tant que variables d’environnement dans le workflow appelé. Au lieu de cela, vous pouvez référencer les entrées à l’aide du contexte inputs.

Exemple de jobs.<job_id>.with

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    with:
      username: mona

jobs.<job_id>.with.<input_id>

Paire composée d’un identificateur de chaîne pour l’entrée et de la valeur de l’entrée. L’identificateur doit correspondre au nom d’une entrée définie par on.workflow_call.inputs.<inputs_id> dans le workflow appelé. Le type de données de la valeur doit correspondre au type défini par on.workflow_call.inputs.<input_id>.type dans le workflow appelé.

Contextes d’expression autorisés : github et needs.

jobs.<job_id>.secrets

Lorsqu’un travail est utilisé pour appeler un workflow réutilisable, vous pouvez utiliser secrets pour fournir un mappage de secrets qui sont passés au workflow appelé.

Les secrets que vous passez doivent correspondre aux noms définis dans le workflow appelé.

Exemple de jobs.<job_id>.secrets

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@main
    secrets:
      access-token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

jobs.<job_id>.secrets.inherit

Utilisez le mot clé inherit pour passer tous les secrets du workflow appelant au workflow appelé. Sont inclus tous les secrets auxquels le workflow appelant a accès, notamment les secrets de l’organisation, des dépôts et de l’environnement. Le mot clé inherit peut être utilisé pour passer des secrets entre des dépôts au sein de la même organisation ou entre des organisations au sein de la même entreprise.

Exemple de jobs.<job_id>.secrets.inherit

on:
  workflow_dispatch:

jobs:
  pass-secrets-to-workflow:
    uses: ./.github/workflows/called-workflow.yml
    secrets: inherit

on:
  workflow_call:

jobs:
  pass-secret-to-action:
    runs-on: ubuntu-latest
    steps:
      - name: Use a repo or org secret from the calling workflow.
        run: echo ${{ secrets.CALLING_WORKFLOW_SECRET }}

jobs.<job_id>.secrets.<secret_id>

Paire composée d’un identificateur de chaîne pour le secret et de la valeur du secret. L’identificateur doit correspondre au nom d’un secret défini par on.workflow_call.secrets.<secret_id> dans le workflow appelé.

Contextes d’expression autorisés : github, needs et secrets.

Aide-mémoire de modèle de filtre

Vous pouvez utiliser des caractères spéciaux dans les filtres de chemin, de branche et d’étiquette.

• * : correspond à zéro caractère ou plus, mais ne correspond pas au caractère /. Par exemples, Octo* correspond à Octocat.
• ** : correspond à zéro caractère, quel qu’il soit, ou plus.
• ? : correspond à zéro caractère ou à l’un des caractères précédents.
• + : correspond à l’un des caractères précédents, ou plus.
• [] : correspond à un caractère alphanumérique indiqué entre crochets ou inclus dans des plages. Les plages ne peuvent inclure a-z, A-Z et 0-9. Par exemple, la plage [0-9a-z] correspond à n’importe quel chiffre ou lettre minuscule. Par exemple, [CB]at correspond à Cat ou à Bat, et [1-2]00 correspond à 100 et à 200.
• ! : Au début d’un modèle, neutralise des modèles positifs précédents. Il n’a pas de signification spéciale si ce n’est pas le premier caractère.

Les caractères *, [ et ! sont des caractères spéciaux dans YAML. Si vous commencez un modèle avec *, [ ou !, vous devez placer ce modèle entre guillemets. En outre, si vous utilisez une séquence de flux avec un modèle contenant [ et/ou ], le modèle doit être placé entre guillemets.

# Valid
paths:
  - '**/README.md'

# Invalid - creates a parse error that
# prevents your workflow from running.
paths:
  - **/README.md

# Valid
branches: [ main, 'release/v[0-9].[0-9]' ]

# Invalid - creates a parse error
branches: [ main, release/v[0-9].[0-9] ]

Pour plus d’informations sur la syntaxe des filtres de branche, d’étiquette et de chemin, consultez « on.<push>.<branches|tags> », « on.<pull_request>.<branches|tags> » et « on.<push|pull_request>.paths ».

Modèles pour établir une correspondance avec des branches et des étiquettes

Modèles pour établir une correspondance avec des chemins de fichiers

Les modèles de chemin doivent correspondre au chemin complet et commencer à la racine du dépôt.