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 de votre flux de travail. GitHub affiche les noms de vos workflows sous l’onglet « Actions » de votre dépôt. Si vous omettez name, GitHub lui attribue le chemin du fichier de workflow relatif à la racine du dépôt.

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

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/**'

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 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 beta/3-alpha (refs/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 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'

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 même 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 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 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 « Contextes ».

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 la « Aide-mémoire de modèle de filtre ».

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.

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

Valeurs d’accès et étendues disponibles :

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 étendues, toutes celles qui ne sont pas spécifiées sont définies sur none.

Vous pouvez utiliser la syntaxe suivante afin de définir l’accès en lecture ou en écriture pour toutes les étendues disponibles :

permissions: read-all|write-all

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

permissions: {}
``` 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 « [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks) ».

### Exemple : Affectation d’autorisations à GITHUB_TOKEN

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.

```yaml
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

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 le contexte github. Pour plus d’informations sur les expressions, consultez « Expressions ».

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

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 ou workflow en attente dans le groupe d’accès concurrentiel est annulé. 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.

Exemples : Utilisation de la concurrence et du comportement par défaut

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

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

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

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

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 connaître 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 « 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.

Valeurs d’accès et étendues disponibles :

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 étendues, toutes celles qui ne sont pas spécifiées sont définies sur none.

Vous pouvez utiliser la syntaxe suivante afin de définir l’accès en lecture ou en écriture pour toutes les étendues disponibles :

permissions: read-all|write-all

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

permissions: {}
``` 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 « [AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-private-repository-forks) ».

### Exemple : Définition d’autorisations pour un travail spécifique

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 étendues `issues` et `pull-requests`. Toutes les autres étendues sont privées d’accès.

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

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 « Expressions ».

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 « Contextes ».

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

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@v3
      - uses: actions/setup-node@v3
        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 les exécuteurs en fonction des étiquettes qui leur sont affectées.

• Vous pouvez fournir runs-on sous la forme d’une chaîne unique ou d’un tableau de chaînes.

• Si vous spécifiez un tableau de chaînes, votre workflow s’exécute sur n’importe quel exécuteur qui correspond à toutes les valeurs runs-on spécifiées.

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

Remarque : Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.

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

Si vous utilisez un exécuteur hébergé par GitHub, chaque travail s’exécute sur une nouvelle instance d’une image d’exécuteur spécifiée par runs-on.

Les types d’exécuteurs hébergés par GitHub disponibles sont les suivants :

Exemple : Spécification d’un système d’exploitation

runs-on: ubuntu-latest

Pour plus d’informations, consultez « À propos 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é.

Tous les exécuteurs autohébergés ont l’étiquette self-hosted. L’utilisation de cette seule étiquette permet de sélectionner n’importe quel exécuteur autohébergé. Pour sélectionner des exécuteurs qui répondent à certains critères, par exemple le système d’exploitation ou l’architecture, nous vous recommandons de fournir un tableau d’étiquettes qui commence par self-hosted (doit être listé en premier), et qui comprend des étiquettes supplémentaires selon les besoins. 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.

Bien que l’étiquette self-hosted ne soit pas obligatoire, nous vous recommandons vivement de la spécifier quand vous utilisez des exécuteurs autohébergés pour avoir la certitude que votre travail ne spécifie pas par inadvertance des exécuteurs, actuels ou futurs, hébergés sur GitHub.

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

jobs.<job_id>.environment

Utilisez jobs.<job_id>.environment pour définir l’environnement référencé par le travail. La validation de toutes les règles de protection d’environnement doit être réussie pour qu’un travail référençant l’environnement soit envoyé à un exécuteur. Pour plus d’informations, consultez « Utilisation d’environnements pour le déploiement ».

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

L’URL peut être une expression et peut utiliser n’importe quel contexte à l’exception du contexte secrets. Pour plus d’informations sur les expressions, consultez « Expressions ».

Exemple : Utilisation de la sortie en tant qu’URL

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

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 « Expressions ».

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

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 ou workflow en attente dans le groupe d’accès concurrentiel est annulé. 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.

Exemples : Utilisation de la concurrence et du comportement par défaut

concurrency: staging_environment

concurrency: ci-${{ github.ref }}

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

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

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

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.

Pour utiliser les sorties de travail dans un travail dépendant, vous pouvez utiliser le contexte needs. Pour plus d’informations, consultez « Contextes ».

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 "::set-output name=test::hello"
      - id: step2
        run: echo "::set-output name=test::world"
  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - env:
          OUTPUT1: ${{needs.job1.outputs.output1}}
          OUTPUT2: ${{needs.job1.outputs.output2}}
        run: echo "$OUTPUT1 $OUTPUT2"

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. Le contexte et l’expression ne sont pas autorisés dans cette section.

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

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 connaître 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 « Contextes ».

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 « Contextes ».

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

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 « Expressions ».

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 « Contextes » et « Secrets chiffrés ».

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@v3
  # Reference a specific version
  - uses: actions/checkout@v3.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.

jobs:
  my_first_job:
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
      - name: Use local my-action
        uses: ./.github/actions/my-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 comme secret chiffré. Pour plus d’informations, consultez « Managing your personal access tokens » et « Secrets chiffrés ».

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@v3
        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écutez des programmes en ligne de commande avec 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
  

À 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

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

Vous pouvez remplacer les paramètres d’interpréteur de commandes par défaut dans le système d’exploitation de l’exécuteur à 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.

Exemple : Exécution d’un script à l’aide de bash

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

Exemple : Exécution d’un script à l’aide de cmd Windows

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

Exemple : Exécution d’un script à l’aide de PowerShell Core

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

Exemple : Utilisation de PowerShell Desktop pour exécuter un script

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

Exemple : Exécution d’un script Python

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

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
    run: |
      print %ENV
    shell: perl {0}

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:

  • Comportement Fail-fast avec set -eo pipefail : cette option est définie quand shell: bash est spécifié explicitement. Elle n’est pas appliquée par défaut.
  • 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 « Contextes ».

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.

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 délais d’exécution des travaux, 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 connaître les limites d’utilisation des exécuteurs auto-hé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 « Utilisation d’une matrice pour vos travaux ».

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 « Contextes ».

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@v3
        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@v3
        with:
          node-version: ${{ matrix.version }}

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 « Contextes ».

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@v3
        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 six travaux, 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: [12, 14, 16]
        include:
          - os: windows-latest
            node: 16
            npm: 6
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v3
        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 a la valeur 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:14.16
      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:14.16

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 d’hôte Docker, mais pas le port du conteneur, le port du conteneur est attribué de manière aléatoire à un port libre. GitHub définit le port de conteneur affecté dans le contexte ${{job.services.<service_name>.ports}}. Dans cet exemple, vous pouvez accéder aux ports de conteneur de service à l’aide des contextes ${{ job.services.nginx.ports['8080'] }} and ${{ 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 TCP port 6379 on Docker host to a random free port on the Redis container
    ports:
      - 6379/tcp

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.

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 des workflows réutilisables dans les dépôts publics et internes.
• ./.github/workflows/{filename} pour des flux de travail réutilisables dans le même dépôt.

{ref} peut être un SHA, une étiquette de mise en production ou un nom de branche. Le SHA de validation est le plus sûr 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.

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 ne sont pas 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 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.