Workflow syntax for GitHub Actions

About YAML syntax for workflows

Workflow files use YAML syntax, and must have either a .yml or .yaml file extension. Si vous débutez avec YAML et souhaitez en savoir plus, consultez Découvrir YAML en Y minutes.

You must store workflow files in the .github/workflows directory of your repository.

name

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

run-name

The name for workflow runs generated from the workflow. GitHub displays the workflow run name in the list of workflow runs on your repository's "Actions" tab. If run-name is omitted or is only whitespace, then the run name is set to event-specific information for the workflow run. For example, for a workflow triggered by a push or pull_request event, it is set as the commit message or the title of the pull request.

This value can include expressions and can reference the github and inputs contexts.

Example of run-name

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

on

Pour déclencher automatiquement un workflow, utilisez on pour définir les événements qui peuvent conduire à l’exécution du workflow. Pour obtenir la liste des événements disponibles, consultez Events that trigger workflows.

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 Events that trigger workflows.

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 Events that trigger 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 l’Workflow syntax for GitHub Actions.

Example: Including branches

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

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

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

Vous ne devez pas utiliser le filtrage de chemin d’accès ou de branche pour ignorer les exécutions de workflow si celui-ci doit aboutir avant la fusion. Pour plus d’informations, consultez « Exécutions de workflow ignorées » et « Règles disponibles pour les ensembles de règles ».

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

Example: Excluding branches

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

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

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

Example: Including and excluding 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 flux de travail ne s’exécutera pas pour les événements affectant la référence Git non définie. Si vous définissez ni tags/tags-ignore ou branches/branches-ignore, le flux de travail sera exécuté 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 l’Workflow syntax for GitHub Actions.

Example: Including branches and tags

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

Example: Excluding branches and tags

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

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

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

Example: Including and excluding branches and tags

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

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

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

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

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

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

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

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

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

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

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

Example: Including paths

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

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

Vous ne devez pas utiliser le filtrage de chemin d’accès ou de branche pour ignorer les exécutions de workflow si celui-ci doit aboutir avant la fusion. Pour plus d’informations, consultez « Exécutions de workflow ignorées » et « Règles disponibles pour les ensembles de règles ».

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

Example: Excluding paths

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

Example: Including and excluding paths

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

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

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

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

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

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

Git diff comparisons

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

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 Events that trigger workflows.

on.workflow_call

Use on.workflow_call to define the inputs and outputs for a reusable workflow. You can also map the secrets that are available to the called workflow. For more information on reusable workflows, see Réutilisation des workflows.

on.workflow_call.inputs

When using the workflow_call keyword, you can optionally specify inputs that are passed to the called workflow from the caller workflow. For more information about the workflow_call keyword, see Events that trigger workflows.

In addition to the standard input parameters that are available, on.workflow_call.inputs requires a type parameter. For more information, see on.workflow_call.inputs.<input_id>.type.

If a default parameter is not set, the default value of the input is false for a boolean, 0 for a number, and "" for a string.

Within the called workflow, you can use the inputs context to refer to an input. For more information, see Accessing contextual information about workflow runs.

If a caller workflow passes an input that is not specified in the called workflow, this results in an error.

Example of 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 }}

For more information, see Réutilisation des workflows.

on.workflow_call.inputs.<input_id>.type

Required if input is defined for the on.workflow_call keyword. The value of this parameter is a string specifying the data type of the input. This must be one of: boolean, number, or string.

on.workflow_call.outputs

A map of outputs for a called workflow. Called workflow outputs are available to all downstream jobs in the caller workflow. Each output has an identifier, an optional description, and a value. The value must be set to the value of an output from a job within the called workflow.

In the example below, two outputs are defined for this reusable workflow: workflow_output1 and workflow_output2. These are mapped to outputs called job_output1 and job_output2, both from a job called my_job.

Example of 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 }}

For information on how to reference a job output, see jobs.<job_id>.outputs. For more information, see Réutilisation des workflows.

on.workflow_call.secrets

A map of the secrets that can be used in the called workflow.

Within the called workflow, you can use the secrets context to refer to a secret.

If a caller workflow passes a secret that is not specified in the called workflow, this results in an error.

Example of 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>

A string identifier to associate with the secret.

on.workflow_call.secrets.<secret_id>.required

A boolean specifying whether the secret must be supplied.

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 l’Workflow syntax for GitHub Actions.

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

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

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

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

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

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

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

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

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

on.workflow_dispatch

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

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

on.workflow_dispatch.inputs

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

Example of 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

A boolean specifying whether the input must be supplied.

on.workflow_dispatch.inputs.<input_id>.type

The value of this parameter is a string specifying the data type of the input. This must be one of: boolean, choice, number, environment or string.

permissions

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

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

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

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

Defining access for the GITHUB_TOKEN scopes

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

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

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

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

permissions: read-all

permissions: write-all

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

permissions: {}

Changing the permissions in a forked repository

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

Setting the GITHUB_TOKEN permissions for all jobs in a workflow

You can specify permissions at the top level of a workflow, so that the setting applies to all jobs in the workflow.

Example: Setting the GITHUB_TOKEN permissions for an entire workflow

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

name: "My workflow"

on: [ push ]

permissions: read-all

jobs:
  ...

env

A map of variables that are available to the steps of all jobs in the workflow. You can also set variables that are only available to the steps of a single job or to a single step. For more information, see jobs.<job_id>.env and jobs.<job_id>.steps[*].env.

Variables in the env map cannot be defined in terms of other variables in the map.

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.

Example of env

env:
  SERVER: production

defaults

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

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

defaults.run

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

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

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

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

defaults.run.shell

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

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

defaults.run.working-directory

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

concurrency

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

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

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

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

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

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

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

on:
  push:
    branches:
      - main

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

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

on:
  push:
    branches:
      - main

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

Exemple : groupes de concurrence

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

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

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

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

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

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

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

on:
  push:
    branches:
      - main

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

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

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

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

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

Exemple : Utilisation d’une valeur de secours

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

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

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

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

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

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

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

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

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

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

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

jobs

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

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

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

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

jobs.<job_id>

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

Exemple : Création de travaux

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

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

jobs.<job_id>.name

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

jobs.<job_id>.permissions

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

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

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

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

Defining access for the GITHUB_TOKEN scopes

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

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

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

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

permissions: read-all

permissions: write-all

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

permissions: {}

Changing the permissions in a forked repository

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

Example: Setting the GITHUB_TOKEN permissions for one job in a workflow

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

jobs:
  stale:
    runs-on: ubuntu-latest

    permissions:
      issues: write
      pull-requests: write

    steps:
      - uses: actions/stale@v9

jobs.<job_id>.needs

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

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

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

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

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

1. job1
2. job2
3. job3

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

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

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

jobs.<job_id>.if

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

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

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

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

Pour plus d’informations, consultez « Evaluate expressions in workflows and actions ».

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

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

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

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

jobs.<job_id>.runs-on

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

• La machine de destination peut être une machine d'exécution auto-hébergée

• Vous pouvez cibler les coureurs en fonction des étiquettes qui leur ont été attribuées, de leur appartenance à un groupe ou d'une combinaison de ces éléments.

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

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

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

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

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

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

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

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

Choosing GitHub-hosted runners

Choosing self-hosted runners

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

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

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

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

runs-on: [self-hosted, linux]

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

Choosing runners in a group

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

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

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

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

Exemple : combinaison de groupes et d’étiquettes

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

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

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

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

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

Utilisation de org/:

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

Utilisation de ent/:

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

jobs.<job_id>.environment

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

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

Exemple : Utilisation d’un seul nom d’environnement

environment: staging_environment

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

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

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

Exemple : Utilisation de la sortie en tant qu’URL

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

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

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

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

jobs.<job_id>.concurrency

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

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

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

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

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

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

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

on:
  push:
    branches:
      - main

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

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

on:
  push:
    branches:
      - main

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

Exemple : groupes de concurrence

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

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

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

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

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

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

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

on:
  push:
    branches:
      - main

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

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

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

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

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

Exemple : Utilisation d’une valeur de secours

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

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

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

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

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

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

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

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

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

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

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

jobs.<job_id>.outputs

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

La taille maximale des sorties est de 1 Mo par projet. La taille totale maximale de toutes les sorties d’une exécution de workflow est de 50 Mo. La taille est approximative et basée sur l’encodage UTF-16.

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

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

Pour utiliser les sorties de travail dans un travail dépendant, vous pouvez utiliser le contexte needs. Pour plus d’informations, consultez « Accessing contextual information about workflow runs ».

Exemple : Définition de sorties pour un travail

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

Utilisation des sorties d'un travail dans un travail matriciel

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

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

jobs.<job_id>.env

A map of variables that are available to all steps in the job. You can set variables for the entire workflow or an individual step. For more information, see env and 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.

Example of jobs.<job_id>.env

jobs:
  job1:
    env:
      FIRST_NAME: Mona

jobs.<job_id>.defaults

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

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

jobs.<job_id>.defaults.run

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

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

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

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

jobs.<job_id>.defaults.run.shell

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

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

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

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

Example: Setting default run step options for a job

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

jobs.<job_id>.steps

A job contains a sequence of tasks called steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry. Not all steps run actions, but all actions run as a step. Each step runs in its own process in the runner environment and has access to the workspace and filesystem. Because steps run in their own process, changes to environment variables are not preserved between steps. GitHub provides built-in steps to set up and complete a job.

GitHub only displays the first 1,000 checks, however, you can run an unlimited number of steps as long as you are within the workflow usage limits. For more information, see Limites d’utilisation, facturation et administration for GitHub-hosted runners and Usage limits for self-hosted runners for self-hosted runner usage limits.

Example of 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

A unique identifier for the step. You can use the id to reference the step in contexts. For more information, see Accessing contextual information about workflow runs.

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

You can use the if conditional to prevent a step from running unless a condition is met. 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 Accessing contextual information about workflow runs.

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

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

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

For more information, see Evaluate expressions in workflows and actions.

Example: Using contexts

This step only runs when the event type is a pull_request and the event action is 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.

Example: Using status check functions

The my backup step only runs when the previous step of a job fails. For more information, see Evaluate expressions in workflows and actions.

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

Example: Using secrets

Secrets cannot be directly referenced in if: conditionals. Instead, consider setting secrets as job-level environment variables, then referencing the environment variables to conditionally run steps in the job.

If a secret has not been set, the return value of an expression referencing the secret (such as ${{ secrets.SuperSecret }} in the example) will be an empty string.

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

For more information, see Accessing contextual information about workflow runs and Utilisation de secrets dans GitHub Actions.

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

A name for your step to display on GitHub.

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

Selects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in a published Docker container image.

We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.

• Using the commit SHA of a released action version is the safest for stability and security.
• If the action publishes major version tags, you should expect to receive critical fixes and security patches while still retaining compatibility. Note that this behavior is at the discretion of the action's author.
• Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

Some actions require inputs that you must set using the with keyword. Review the action's README file to determine the inputs required.

Actions are either JavaScript files or Docker containers. If the action you're using is a Docker container you must run the job in a Linux environment. For more details, see runs-on.

Example: Using versioned actions

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

Example: Using a public action

{owner}/{repo}@{ref}

You can specify a branch, ref, or SHA in a public GitHub repository.

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

Example: Using a public action in a subdirectory

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

A subdirectory in a public GitHub repository at a specific branch, ref, or SHA.

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

Example: Using an action in the same repository as the workflow

./path/to/dir

The path to the directory that contains the action in your workflow's repository. You must check out your repository before using the action.

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

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

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

Exemple de fichier de workflow :

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

Example: Using a Docker Hub action

docker://{image}:{tag}

A Docker image published on Docker Hub.

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

Example: Using a Docker public registry action

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

A Docker image in a public registry. This example uses the Google Container Registry at gcr.io.

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

Example: Using an action inside a different private repository than the workflow

Your workflow must checkout the private repository and reference the action locally. Generate a personal access token and add the token as a secret. For more information, see Gestion de vos jetons d'accès personnels and Utilisation de secrets dans GitHub Actions.

Replace PERSONAL_ACCESS_TOKEN in the example with the name of your secret.

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

Alternatively, use a GitHub App instead of a personal access token in order to ensure your workflow continues to run even if the personal access token owner leaves. For more information, see Effectuer des requêtes d’API authentifiées avec une application GitHub dans un workflow GitHub Actions.

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

Runs command-line programs that do not exceed 21,000 characters using the operating system's shell. If you do not provide a name, the step name will default to the text specified in the run command.

Commands run using non-login shells by default. You can choose a different shell and customize the shell used to run commands. For more information, see jobs.<job_id>.steps[*].shell.

Each run keyword represents a new process and shell in the runner environment. When you provide multi-line commands, each line runs in the same shell. For example:

• A single-line command:

  - name: Install Dependencies
    run: npm install
  

• A multi-line command:

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

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

Using the working-directory keyword, you can specify the working directory of where to run the command.

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

Alternatively, you can specify a default working directory for all run steps in a job, or for all run steps in the entire workflow. For more information, see defaults.run.working-directory and jobs.<job_id>.defaults.run.working-directory.

You can also use a run step to run a script. For more information, see Ajout de scripts à votre workflow.

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

You can override the default shell settings in the runner's operating system and the job's default using the shell keyword. You can use built-in shell keywords, or you can define a custom set of shell options. The shell command that is run internally executes a temporary file that contains the commands specified in the run keyword.

Alternatively, you can specify a default shell for all run steps in a job, or for all run steps in the entire workflow. For more information, see defaults.run.shell and jobs.<job_id>.defaults.run.shell.

Example: Running a command using Bash

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

Example: Running a command using Windows cmd

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

Example: Running a command using PowerShell Core

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

Example: Using PowerShell Desktop to run a command

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

Example: Running an inline Python script

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

Custom shell

You can set the shell value to a template string using command [options] {0} [more_options]. GitHub interprets the first whitespace-delimited word of the string as the command, and inserts the file name for the temporary script at {0}.

For example:

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

The command used, perl in this example, must be installed on the runner.

Exit codes and error action preference

For built-in shell keywords, we provide the following defaults that are executed by GitHub-hosted runners. You should use these guidelines when running shell scripts.

• bash/sh:

  • By default, fail-fast behavior is enforced using set -e for both sh and bash. When shell: bash is specified, -o pipefail is also applied to enforce early exit from pipelines that generate a non-zero exit status.
  • You can take full control over shell parameters by providing a template string to the shell options. For example, bash {0}.
  • sh-like shells exit with the exit code of the last command executed in a script, which is also the default behavior for actions. The runner will report the status of the step as fail/succeed based on this exit code.

• powershell/pwsh

  • Fail-fast behavior when possible. For pwsh and powershell built-in shell, we will prepend $ErrorActionPreference = 'stop' to script contents.
  • We append if ((Test-Path -LiteralPath variable:\LASTEXITCODE)) { exit $LASTEXITCODE } to powershell scripts so action statuses reflect the script's last exit code.
  • Users can always opt out by not using the built-in shell, and providing a custom shell option like: pwsh -File {0}, or powershell -Command "& '{0}'", depending on need.

• cmd

  • There doesn't seem to be a way to fully opt into fail-fast behavior other than writing your script to check each error code and respond accordingly. Because we can't actually provide that behavior by default, you need to write this behavior into your script.
  • cmd.exe will exit with the error level of the last program it executed, and it will return the error code to the runner. This behavior is internally consistent with the previous sh and pwsh default behavior and is the cmd.exe default, so this behavior remains intact.

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

A map of the input parameters defined by the action. Each input parameter is a key/value pair. Input parameters are set as environment variables. The variable is prefixed with INPUT_ and converted to upper case.

Input parameters defined for a Docker container must use args. For more information, see jobs.<job_id>.steps[*].with.args.

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

Defines the three input parameters (first_name, middle_name, and last_name) defined by the hello_world action. These input variables will be accessible to the hello-world action as INPUT_FIRST_NAME, INPUT_MIDDLE_NAME, and INPUT_LAST_NAME environment variables.

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

A string that defines the inputs for a Docker container. GitHub passes the args to the container's ENTRYPOINT when the container starts up. An array of strings is not supported by this parameter. A single argument that includes spaces should be surrounded by double quotes "".

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

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

1. Document required arguments in the action's README and omit them from the CMD instruction.
2. Use defaults that allow using the action without specifying any args.
3. If the action exposes a --help flag, or something similar, use that as the default to make your action self-documenting.

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

Overrides the Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Unlike the Docker ENTRYPOINT instruction which has a shell and exec form, entrypoint keyword accepts only a single string defining the executable to be run.

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

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

The entrypoint keyword is meant to be used with Docker container actions, but you can also use it with JavaScript actions that don't define any inputs.

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

Sets variables for steps to use in the runner environment. You can also set variables for the entire workflow or a job. For more information, see env and 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.

Public actions may specify expected variables in the README file. If you are setting a secret or sensitive value, such as a password or token, you must set secrets using the secrets context. For more information, see Accessing contextual information about workflow runs.

Example of 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

Prevents a job from failing when a step fails. Set to true to allow a job to pass when this step fails.

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

The maximum number of minutes to run the step before killing the process.

Fractional values are not supported. timeout-minutes must be a positive integer.

jobs.<job_id>.timeout-minutes

The maximum number of minutes to let a job run before GitHub automatically cancels it. Default: 360

If the timeout exceeds the job execution time limit for the runner, the job will be canceled when the execution time limit is met instead. For more information about job execution time limits, see Limites d’utilisation, facturation et administration for GitHub-hosted runners and Usage limits for self-hosted runners for self-hosted runner usage limits.

jobs.<job_id>.strategy

Use jobs.<job_id>.strategy to use a matrix strategy for your jobs. 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. For more information, see Exécution de variantes de tâches dans un workflow.

jobs.<job_id>.strategy.matrix

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

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

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

Par défaut, GitHub 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 et à ceux qui sont auto-hé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 « Accessing contextual information about workflow runs ».

Example: Using a single-dimension matrix

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

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

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

Example: Using a multi-dimension matrix

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

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

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

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

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

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

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

Cette matrice produit quatre travaux avec des contextes correspondants.

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

Example: Using contexts to create matrices

Vous pouvez utiliser des contextes pour créer des matrices. Pour plus d’informations sur les contextes, consultez « Accessing contextual information about workflow runs ».

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 Events that trigger workflows.

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

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

jobs.<job_id>.strategy.matrix.include

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

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

Par exemple, cette matrice :

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

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

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

en suivant cette logique :

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

Example: Expanding configurations

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

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

Example: Adding configurations

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

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

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

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

jobs.<job_id>.strategy.matrix.exclude

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

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

jobs.<job_id>.strategy.fail-fast

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

jobs.<job_id>.strategy.fail-fast s’applique à l’ensemble de la matrice. Si jobs.<job_id>.strategy.fail-fast est défini sur true, ou son expression aboutit à true, GitHub 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 optimise le nombre de travaux exécutés en parallèle en fonction de la disponibilité des exécuteurs. 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

Prevents a workflow run from failing when a job fails. Set to true to allow a workflow run to pass when this job fails.

Example: Preventing a specific failing matrix job from failing a workflow run

You can allow specific jobs in a job matrix to fail without failing the workflow run. For example, if you wanted to only allow an experimental job with node set to 15 to fail without failing the workflow run.

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

jobs.<job_id>.container

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

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

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

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

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

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

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

jobs.<job_id>.container.image

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

jobs.<job_id>.container.credentials

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

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

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

jobs.<job_id>.container.env

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

jobs.<job_id>.container.ports

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

jobs.<job_id>.container.volumes

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

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

<source>:<destinationPath>.

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

Exemple : Montage de volumes dans un conteneur

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

jobs.<job_id>.container.options

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

jobs.<job_id>.services

Used to host service containers for a job in a workflow. Service containers are useful for creating databases or cache services like Redis. The runner automatically creates a Docker network and manages the life cycle of the service containers.

If you configure your job to run in a container, or your step uses container actions, you don't need to map ports to access the service or action. Docker automatically exposes all ports between containers on the same Docker user-defined bridge network. You can directly reference the service container by its hostname. The hostname is automatically mapped to the label name you configure for the service in the workflow.

If you configure the job to run directly on the runner machine and your step doesn't use a container action, you must map any required Docker service container ports to the Docker host (the runner machine). You can access the service container using localhost and the mapped port.

For more information about the differences between networking service containers, see À propos des conteneurs de service.

Example: Using localhost

This example creates two services: nginx and redis. When you specify the container port but not the host port, the container port is randomly assigned to a free port on the host. GitHub sets the assigned host port in the ${{job.services.<service_name>.ports}} context. In this example, you can access the service host ports using the ${{ job.services.nginx.ports['80'] }} and ${{ job.services.redis.ports['6379'] }} contexts.

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

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

The Docker image to use as the service container to run the action. The value can be the Docker Hub image name or a registry name.

If jobs.<job_id>.services.<service_id>.image is assigned an empty string, the service will not start. You can use this to set up conditional services, similar to the following example.

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

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

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

Example of 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

Sets a map of environment variables in the service container.

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

Sets an array of ports to expose on the service container.

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

Sets an array of volumes for the service container to use. You can use volumes to share data between services or other steps in a job. You can specify named Docker volumes, anonymous Docker volumes, or bind mounts on the host.

To specify a volume, you specify the source and destination path:

<source>:<destinationPath>.

The <source> is a volume name or an absolute path on the host machine, and <destinationPath> is an absolute path in the container.

Example of 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

Additional Docker container resource options. For a list of options, see docker create options.

jobs.<job_id>.uses

The location and version of a reusable workflow file to run as a job. Use one of the following syntaxes:

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

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

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

Example of 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

For more information, see Réutilisation des workflows.

jobs.<job_id>.with

When a job is used to call a reusable workflow, you can use with to provide a map of inputs that are passed to the called workflow.

Any inputs that you pass must match the input specifications defined in the called workflow.

Unlike jobs.<job_id>.steps[*].with, the inputs you pass with jobs.<job_id>.with are not available as environment variables in the called workflow. Instead, you can reference the inputs by using the inputs context.

Example of 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>

A pair consisting of a string identifier for the input and the value of the input. The identifier must match the name of an input defined by on.workflow_call.inputs.<inputs_id> in the called workflow. The data type of the value must match the type defined by on.workflow_call.inputs.<input_id>.type in the called workflow.

Allowed expression contexts: github, and needs.

jobs.<job_id>.secrets

When a job is used to call a reusable workflow, you can use secrets to provide a map of secrets that are passed to the called workflow.

Any secrets that you pass must match the names defined in the called workflow.

Example of 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

Use the inherit keyword to pass all the calling workflow's secrets to the called workflow. This includes all secrets the calling workflow has access to, namely organization, repository, and environment secrets. The inherit keyword can be used to pass secrets across repositories within the same organization, or across organizations within the same enterprise.

Example of 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>

A pair consisting of a string identifier for the secret and the value of the secret. The identifier must match the name of a secret defined by on.workflow_call.secrets.<secret_id> in the called workflow.

Allowed expression contexts: github, needs, and secrets.

Filter pattern cheat sheet

You can use special characters in path, branch, and tag filters.

• *: Matches zero or more characters, but does not match the / character. For example, Octo* matches Octocat.
• **: Matches zero or more of any character.
• ?: Matches zero or one of the preceding character.
• +: Matches one or more of the preceding character.
• [] Matches one alphanumeric character listed in the brackets or included in ranges. Ranges can only include a-z, A-Z, and 0-9. For example, the range[0-9a-z] matches any digit or lowercase letter. For example, [CB]at matches Cat or Bat and [1-2]00 matches 100 and 200.
• !: At the start of a pattern makes it negate previous positive patterns. It has no special meaning if not the first character.

The characters *, [, and ! are special characters in YAML. If you start a pattern with *, [, or !, you must enclose the pattern in quotes. Also, if you use a flow sequence with a pattern containing [ and/or ], the pattern must be enclosed in quotes.

# 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] ]

For more information about branch, tag, and path filter syntax, see on.<push>.<branches|tags>, on.<pull_request>.<branches|tags>, and on.<push|pull_request>.paths.

Patterns to match branches and tags

Patterns to match file paths

Path patterns must match the whole path, and start from the repository's root.