Skip to main content

Réutilisation des workflows

Découvrez comment éviter les doublons quand vous créez un workflow en réutilisant des workflows existants.

Vue d’ensemble

Au lieu de copier et de coller d’un workflow vers un autre, vous pouvez rendre les workflows réutilisables. Vous et toute personne ayant accès au workflow réutilisable peut alors appeler le workflow réutilisable à partir d’un autre workflow.

La réutilisation de workflows évite la duplication. Cela facilite la maintenance des workflows et vous permet de créer plus rapidement de nouveaux workflows en s’appuyant sur le travail des autres, comme vous le faites avec des actions. La réutilisation des workflows favorise également les bonnes pratiques en vous aidant à utiliser des workflows bien conçus, qui ont déjà été testés et qui se sont avérés efficaces. Votre organisation peut créer une bibliothèque de workflows réutilisables qui peuvent être gérés de manière centralisée.

Le diagramme ci-dessous montre une exécution de flux de travail en cours qui utilise un workflow réutilisable.

  • Une fois que chacun des trois travaux de build à gauche du diagramme se termine avec succès, un travail dépendant appelé « Déployer » est exécuté.
  • Le travail « Déployer » appelle un workflow réutilisable qui contient trois travaux : « Préproduction », « Révision » et « Production ».
  • Le travail de déploiement « Production » s’exécute uniquement une fois que le travail « Préproduction » s’est correctement terminé.
  • Quand un travail cible un environnement, l’exécution du workflow affiche une barre de progression qui indique le nombre d’étapes du travail. Dans le diagramme ci-dessous, le travail « Production » contient 8 étapes, l’étape 6 étant en cours de traitement.
  • L’utilisation d’un workflow réutilisable pour exécuter des travaux de déploiement vous permet d’exécuter ces travaux pour chaque build sans dupliquer du code dans les workflows.

Schéma d’un workflow appelant un workflow réutilisable.

Un workflow qui utilise un autre workflow est appelé workflow « appelant ». Le workflow réutilisable est workflow « appelé ». Un workflow appelant peut utiliser plusieurs workflows appelés. Chaque workflow appelé est référencé sur une seule ligne. Le résultat est que le workflow appelant peut ne contenir que quelques lignes de code YAML, mais effectuer un grand nombre de tâches quand il est exécuté. Lorsque vous réutilisez un workflow, l’ensemble du workflow appelé est utilisé, comme s’il faisait partie du workflow appelant.

Si vous réutilisez un workflow d’un autre dépôt, toutes les actions du workflow appelé s’exécutent comme si elles faisaient partie du workflow appelant. Par exemple, si le workflow appelé utilise actions/checkout, l’action extrait le contenu du dépôt qui héberge le workflow appelant, et non le workflow appelé.

Lorsqu’un workflow réutilisable est déclenché par un workflow appelant, le contexte github est toujours associé au workflow appelant. Le workflow appelé est automatiquement autorisé à accéder à github.token et à secrets.GITHUB_TOKEN. Pour plus d’informations sur le contexte github, consultez « Contextes ».

Vous pouvez afficher les workflows réutilisés référencés dans vos workflows GitHub Actions en tant que dépendances dans le graphique des dépendances du dépôt contenant vos workflows. Pour plus d’informations, consultez « À propos du graphique des dépendances ».

Workflows réutilisables et workflows de démarrage

Les workflows de démarrage permettent à tous les membres de votre organisation disposant de l’autorisation de créer des workflows de le faire plus rapidement et plus facilement. Lorsque des utilisateurs créent un workflow, ils peuvent choisir un workflow de démarrage, et tout ou partie du travail d’écriture du workflow sera effectué à leur place. Dans un workflow de démarrage, vous pouvez également référencer des workflows réutilisables pour permettre aux utilisateurs de tirer facilement parti de la réutilisation de code de workflow géré de manière centralisée. Si vous utilisez un SHA de commit lors du référencement du workflow réutilisable, vous garantissez que tous ceux qui réutilisent ce workflow utiliseront toujours le même code YAML. Toutefois, si vous référencez un workflow réutilisable par une étiquette ou une branche, assurez-vous que vous pouvez approuver cette version du workflow. Pour plus d’informations, consultez « Durcissement de la sécurité pour GitHub Actions ».

Pour plus d’informations, consultez « Création de workflows de démarrage pour votre organisation ».

Accès aux workflows réutilisables

Un workflow réutilisable peut être utilisé par un autre workflow si l’une ou l’autre des conditions suivantes est vraie :

Remarque : Pour améliorer la sécurité, GitHub Actions ne prend pas en charge les redirections pour les actions ou les workflows réutilisables. Cela signifie que quand le propriétaire, le nom du dépôt d’une action ou le nom d’une action est modifié, tous les workflows utilisant cette action avec le nom précédent vont échouer.

Utilisation des exécuteurs

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

L’affectation d’exécuteurs hébergés par GitHub est toujours évaluée à l’aide du contexte de l’appelant uniquement. La facturation des exécuteurs hébergés par GitHub est toujours associée à l’appelant. Le workflow appelant ne peut pas utiliser des exécuteurs hébergés par GitHub à partir du dépôt appelé. Pour plus d’informations, consultez « Utilisation des exécuteurs hébergés par GitHub ».

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

Les workflows appelés qui appartiennent au même utilisateur ou à la même organisation que le workflow appelant peuvent accéder aux exécuteurs auto-hébergés à partir du contexte de l’appelant. Cela signifie qu’un workflow appelé peut accéder aux exécuteurs auto-hébergés qui se trouvent :

  • Dans le dépôt appelant
  • Dans l’organisation du dépôt appelant, à condition que l’exécuteur ait été mis à la disposition du dépôt appelant

Limites

  • Vous pouvez connecter jusqu’à quatre niveaux de workflows. Pour plus d’informations, consultez « Imbrication de workflows réutilisables ».

  • Vous pouvez appeler un maximum de 20 workflows réutilisables à partir d’un fichier de workflow unique. Cette limite inclut toutes les arborescences de workflows réutilisables imbriqués qui peuvent être appelés à partir de votre fichier de workflows de l’appelant de niveau supérieur.

    Par exemple, workflow_appelant_niveau_supérieur.ymlworkflow_appelé-1.ymlworkflow_appelé-2.yml compte comme deux workflows réutilisables.

  • Toutes les variables d’environnement configurées dans un contexte env défini au niveau du workflow dans le workflow appelant ne sont pas propagées au workflow appelé. Pour plus d’informations, consultez « Variables » et « Contextes ».

  • De même, les variables d’environnement configurées dans le contexte env, défini dans le workflow appelé, ne sont pas accessibles dans le contexte env du workflow de l’appelant. Au lieu de cela, vous devez utiliser les sorties du workflow réutilisable. Pour plus d’informations, consultez « Utilisation de sorties à partir d’un flux de travail réutilisable ».

  • Pour réutiliser des variables dans plusieurs workflows, définissez-les au niveau de l’organisation, du dépôt ou de l’environnement, et référencez-les à l’aide du contexte vars. Pour plus d’informations, consultez « Variables » et « Contextes ».

  • Les workflows réutilisables sont appelés directement au sein d’un travail, et non à partir d’une étape de travail. Vous ne pouvez donc pas utiliser GITHUB_ENV pour passer des valeurs aux étapes de travail dans le workflow de l’appelant.

Création d’un workflow réutilisable

Les workflows réutilisables sont des fichiers au format YAML, très similaires à tout autre fichier de workflow. Comme avec d’autres fichiers de workflow, vous localisez les workflows réutilisables dans le répertoire .github/workflows d’un dépôt. Les sous-répertoires du répertoire workflows ne sont pas pris en charge.

Pour qu’un workflow soit réutilisable, les valeurs de on devront inclure workflow_call :

on:
  workflow_call:

Utilisation d’entrées et de secrets dans un workflow réutilisable

Vous pouvez définir des entrées et des secrets, qui peuvent être passés à partir du workflow appelant, puis utilisés dans le workflow appelé. L’utiliser d’une entrée ou d’un secret dans un workflow réutilisable comporte trois étapes.

  1. Dans le workflow réutilisable, utilisez les mots clés inputs et secrets pour définir des entrées ou des secrets qui seront passés à partir d’un workflow appelant.

    on:
      workflow_call:
        inputs:
          config-path:
            required: true
            type: string
        secrets:
          envPAT:
            required: true
    

Pour obtenir des détails sur la syntaxe de la définition d’entrées et de secrets, consultez on.workflow_call.inputs et on.workflow_call.secrets.

  1. Dans le workflow réutilisable, référencez l’entrée ou le secret que vous avez défini(e) dans la clé on à l’étape précédente.

    Remarque :Si les secrets sont hérités par l’utilisation de secrets: inherit dans le workflow d’appel, vous pouvez les référencer même s’ils ne sont pas définis explicitement dans la clé on. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».

    jobs:
      reusable_workflow_job:
        runs-on: ubuntu-latest
        environment: production
        steps:
        - uses: actions/labeler@v4
          with:
            repo-token: ${{ secrets.envPAT }}
            configuration-path: ${{ inputs.config-path }}
    

Dans l’exemple ci-dessus, envPAT est un secret d’environnement qui a été ajouté à l’environnement production. Cet environnement est donc référencé dans le travail.

Remarque : les secrets d’environnement sont des chaînes chiffrées stockées dans un environnement que vous avez défini pour un référentiel. Les secrets d’environnement sont disponibles uniquement pour les travaux de workflow qui référencent l’environnement approprié. Pour plus d’informations, consultez « Utilisation d’environnements pour le déploiement ».

  1. Passez l’entrée ou le secret à partir du workflow appelant.

    Pour transmettre des entrées nommées à un workflow appelé, utilisez le mot clé with dans un travail. Utilisez le mot clé secrets pour transmettre des secrets nommés. Pour les entrées, le type de données de la valeur d’entrée doit correspondre au type spécifié dans le workflow appelé (booléen, nombre ou chaîne).

    jobs:
      call-workflow-passing-data:
        uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
        with:
          config-path: .github/labeler.yml
        secrets:
          envPAT: ${{ secrets.envPAT }}
    

    Les workflows qui appellent des workflows réutilisables dans la même organisation ou entreprise peuvent utiliser le mot clé inherit pour transmettre implicitement les secrets.

    jobs:
      call-workflow-passing-data:
        uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
        with:
          config-path: .github/labeler.yml
        secrets: inherit
    

Exemple de workflow réutilisable

Ce fichier de workflow réutilisable nommé workflow-B.yml (auquel nous ferons référence plus tard dans l’exemple de workflow appelant) prend une chaîne d’entrée et un secret provenant du workflow appelant et les utilise dans une action.

YAML
name: Reusable workflow example

on:
  workflow_call:
    inputs:
      config-path:
        required: true
        type: string
    secrets:
      token:
        required: true

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.token }}
        configuration-path: ${{ inputs.config-path }}

Appel d’un workflow réutilisable

Vous appelez un workflow réutilisable à l’aide du mot clé uses. Contrairement à l’étape dans laquelle vous utilisez des actions dans un workflow, vous appelez des workflows réutilisables directement au sein d’un travail, et non à partir d’étapes de travail.

jobs.<job_id>.uses

Pour référencer des fichiers de workflow réutilisables, utilisez l’une des syntaxes suivantes :

  • {owner}/{repo}/.github/workflows/{filename}@{ref} pour les flux de travail réutilisables dans les dépôts publics 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 pouvez appeler plusieurs workflows, en référençant chacun dans un travail distinct.

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

Passage d’entrées et de secrets à un workflow réutilisable

Pour transmettre des entrées nommées à un workflow appelé, utilisez le mot clé with dans un travail. Utilisez le mot clé secrets pour transmettre des secrets nommés. Pour les entrées, le type de données de la valeur d’entrée doit correspondre au type spécifié dans le workflow appelé (booléen, nombre ou chaîne).

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      envPAT: ${{ secrets.envPAT }}

Les workflows qui appellent des workflows réutilisables dans la même organisation ou entreprise peuvent utiliser le mot clé inherit pour transmettre implicitement les secrets.

jobs:
  call-workflow-passing-data:
    uses: octo-org/example-repo/.github/workflows/reusable-workflow.yml@main
    with:
      config-path: .github/labeler.yml
    secrets: inherit

Utilisation d’une stratégie de matrice avec un workflow réutilisable

Les travaux qui utilisent la stratégie de matrice peuvent appeler un workflow réutilisable.

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 passer différentes entrées à un workflow réutilisable. Pour plus d’informations sur les matrices, consultez « Utilisation d’une matrice pour vos travaux ».

Cet exemple de travail ci-dessous appelle un workflow réutilisable et fait référence au contexte de matrice en définissant la variable target avec les valeurs [dev, stage, prod]. Il va exécuter trois travaux, un pour chaque valeur de la variable.

YAML
jobs:
  ReuseableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

Mots clés pris en charge pour les travaux qui appellent un workflow réutilisable

Lorsque vous appelez un workflow réutilisable, vous ne pouvez utiliser que les mots clés suivants dans le travail contenant l’appel :

Exemple de workflow appelant

Ce fichier de workflow appelle deux fichiers de workflow. Une entrée (config-path) et un secret (token) sont passés au deuxième de ces fichiers, workflow-B.yml (illustré dans l’exemple de workflow réutilisable).

YAML
name: Call a reusable workflow

on:
  pull_request:
    branches:
      - main

jobs:
  call-workflow:
    uses: octo-org/example-repo/.github/workflows/workflow-A.yml@v1

  call-workflow-passing-data:
    permissions:
      contents: read
      pull-requests: write
    uses: octo-org/example-repo/.github/workflows/workflow-B.yml@main
    with:
      config-path: .github/labeler.yml
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}

Imbrication des workflows réutilisables

Vous pouvez connecter un maximum de quatre niveaux de workflows, c’est-à-dire le workflow de l’appelant de niveau supérieur et jusqu’à trois niveaux de workflows réutilisables. Par exemple : caller-workflow.ymlcalled-workflow-1.ymlcalled-workflow-2.ymlcalled-workflow-3.yml. Les boucles ne sont pas autorisées dans l’arborescence de workflows.

À partir d’un workflow réutilisable, vous pouvez appeler un autre workflow réutilisable.

YAML
name: Reusable workflow

on:
  workflow_call:

jobs:
  call-another-reusable:
    uses: octo-org/example-repo/.github/workflows/another-reusable.yml@v1

Passage de secrets à des workflows imbriqués

Vous pouvez utiliser jobs.<job_id>.secrets dans un workflow appelant pour passer des secrets nommés à un workflow appelé directement. Vous pouvez également utiliser jobs.<job_id>.secrets.inherit pour passer tous les secrets du workflow appelant à un workflow directement appelé. Pour plus d’informations, consultez la section « Réutilisation des workflows » ci-dessus et l’article de référence « Workflow syntax for GitHub Actions ». Les secrets sont passés uniquement au workflow appelé directement, de sorte que dans la chaîne de workflow A > B > C, le workflow C ne reçoit les secrets de A que s’ils ont été passés de A à B, puis de B à C.

Dans l’exemple suivant, le workflow A passe tous ses secrets au workflow B à l’aide du mot clé inherit, mais le workflow B ne passe qu’un seul secret au workflow C. Les autres secrets passés au workflow B ne sont pas disponibles pour le workflow C.

jobs:
  workflowA-calls-workflowB:
    uses: octo-org/example-repo/.github/workflows/B.yml@main
    secrets: inherit # pass all secrets
jobs:
  workflowB-calls-workflowC:
    uses: different-org/example-repo/.github/workflows/C.yml@main
    secrets:
      envPAT: ${{ secrets.envPAT }} # pass just this secret

Accès et autorisations

Un workflow qui contient des workflows réutilisables imbriqués échouera si l’un des workflows imbriqués n’est pas accessible au workflow de l’appelant initial. Pour plus d’informations, consultez « Réutilisation des workflows ».

Dans les workflows imbriqués, les autorisations GITHUB_TOKEN ne peuvent être identiques ni plus restrictives. Par exemple, dans la chaîne de workflows A > B > C, si le workflow A dispose d’une autorisation de jeton package: read, B et C ne peuvent pas avoir d’autorisation package: write. Pour plus d’informations, consultez « Authentification par jeton automatique ».

Pour plus d’informations sur l’utilisation de l’API pour déterminer quels fichiers de workflow ont été impliqués dans une exécution de workflow particulière, consultez « Supervision des workflows qui ont été utilisés ».

Utilisation de sorties à partir d’un workflow réutilisable

Un workflow réutilisable peut générer des données que vous souhaitez utiliser dans le workflow appelant. Pour utiliser ces sorties, vous devez les spécifier comme sorties du workflow réutilisable.

Si un workflow réutilisable qui définit une sortie est exécuté avec une stratégie de matrice, la sortie sera celle qui est définie par le dernier workflow réutilisable réussi de la matrice qui définit réellement une valeur. Cela signifie que si le dernier workflow réutilisable réussi définit une chaîne vide pour sa sortie et que l’avant-dernier workflow réutilisable réussi définit une valeur réelle pour sa sortie, la sortie contiendra la valeur de l’avant-dernier workflow réutilisable.

Le workflow réutilisable suivant comprend un seul travail contenant deux étapes. Dans chacune de ces étapes, nous définissons un mot unique comme sortie : « hello » et « world ». Dans la section outputs du travail, nous mappons ces sorties d’étape aux sorties de travail appelées output1 et output2. Dans la section on.workflow_call.outputs, nous définissons ensuite deux sorties pour le workflow lui-même : une appelée firstword que nous mappons à output1, et l’autre appelée secondword que nous mappons à output2.

YAML
name: Reusable workflow

on:
  workflow_call:
    # Map the workflow outputs to job outputs
    outputs:
      firstword:
        description: "The first output string"
        value: ${{ jobs.example_job.outputs.output1 }}
      secondword:
        description: "The second output string"
        value: ${{ jobs.example_job.outputs.output2 }}

jobs:
  example_job:
    name: Generate output
    runs-on: ubuntu-latest
    # Map the job outputs to step outputs
    outputs:
      output1: ${{ steps.step1.outputs.firstword }}
      output2: ${{ steps.step2.outputs.secondword }}
    steps:
      - id: step1
        run: echo "firstword=hello" >> $GITHUB_OUTPUT
      - id: step2
        run: echo "secondword=world" >> $GITHUB_OUTPUT

Nous pouvons maintenant utiliser les sorties dans le workflow appelant, de la même façon que vous utiliseriez les sorties d’un travail au sein du même workflow. Nous faisons référence aux sorties à l’aide des noms définis au niveau du workflow dans le workflow réutilisable : firstword et secondword. Dans ce workflow, job1 appelle le workflow réutilisable et job2 imprime les sorties de ce dernier (« hello world ») dans la sortie standard dans le journal du workflow.

YAML
name: Call a reusable workflow and use its outputs

on:
  workflow_dispatch:

jobs:
  job1:
    uses: octo-org/example-repo/.github/workflows/called-workflow.yml@v1

  job2:
    runs-on: ubuntu-latest
    needs: job1
    steps:
      - run: echo ${{ needs.job1.outputs.firstword }} ${{ needs.job1.outputs.secondword }}

Pour plus d’informations sur l’utilisation des sorties de travail, consultez « Workflow syntax for GitHub Actions ». Si vous souhaitez partager quelque chose d’autre qu’une variable (par exemple, un artefact de build) entre les workflows, consultez « Stockage des données de workflow en tant qu’artefacts ».

Monitoring des workflows en cours d’utilisation

Vous pouvez utiliser l’API REST GitHub pour superviser la façon dont les workflows réutilisables sont utilisés. L’action de journal d’audit prepared_workflow_job est déclenchée lors du démarrage d’un travail de workflow. Les données enregistrées sont les suivantes :

  • repo : organisation/dépôt où se trouve le travail de workflow. Pour un travail qui appelle un autre workflow, il s’agit de l’organisation/du dépôt du workflow appelant.

  • @timestamp : date et heure de démarrage du travail, au format Unix Epoch.

  • job_name : nom du travail qui a été exécuté.

  • calling_workflow_refs - un tableau de chemins de fichiers pour tous les workflows de l’appelant impliqués dans ce travail de workflow. Les éléments du tableau sont dans l’ordre inverse de celui où ils ont été appelés. Par exemple, dans une chaîne de workflows A > B > C, lors de l’affichage des journaux pour un travail dans le workflow C, le tableau est ["octo-org/octo-repo/.github/workflows/B.yml", "octo-org/octo-repo/.github/workflows/A.yml"].

  • calling_workflow_shas - un tableau de SHA pour tous les workflows de l’appelant impliqués dans ce travail de workflow. Le tableau contient le même nombre d’éléments, dans le même ordre, que le tableau calling_workflow_refs.

  • job_workflow_ref : fichier de workflow qui a été utilisé, sous la forme {owner}/{repo}/{path}/{filename}@{ref}. Pour un travail qui appelle un autre workflow, cela identifie le workflow appelé.

Pour plus d’informations sur l’utilisation de l’API REST en vue d’interroger le journal d’audit d’une organisation, consultez « Points de terminaison d’API REST pour les organisations ».

Remarque : Les données d’audit pour prepared_workflow_job ne peuvent être consultées qu’à l’aide de l’API REST. Elles ne sont pas visibles dans l’interface web GitHub, ni incluses dans les données d’audit exportées JSON/CSV.

Réexécution de workflows et de travaux avec des workflows réutilisables

Les workflows réutilisables provenant de référentiels publics peuvent être référencés à l’aide d’un SHA, d’une étiquette de mise en production ou d’un nom de branche. Pour plus d’informations, consultez « Réutilisation des workflows ».

Lorsque vous réexécutez un workflow qui utilise un workflow réutilisable et que la référence n’est pas un SHA, il existe des comportements à prendre en compte :

  • La réexécution de tous les travaux dans un workflow utilise le workflow réutilisable à partir de la référence spécifiée. Pour plus d’informations sur la réexécution de tous les travaux d’un workflow, consultez « Ré-exécution de workflows et de travaux ».
  • La réexécution des travaux ayant échoué ou d’un travail spécifique dans un workflow utilise le workflow réutilisable à partir du même SHA de validation que lors de la première tentative. Pour plus d’informations sur la réexécution des travaux en échec d’un workflow, consultez « Ré-exécution de workflows et de travaux ». Pour plus d’informations sur la réexécution d’un travail spécifique d’un workflow, consultez « Ré-exécution de workflows et de travaux ».

Étapes suivantes

Pour continuer à découvrir GitHub Actions, consultez « Événements qui déclenchent des flux de travail ».