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.

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

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.

Diagramme d’un workflow réutilisable pour le déploiement

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 « Syntaxe de contexte et d’expression pour GitHub Actions ».

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 « Renforcement 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 n’importe laquelle des conditions suivantes est vraie :

  • Les deux workflows se trouvent dans le même dépôt.
  • Le workflow appelé est stocké dans un dépôt public.
  • Le workflow appelé est stocké dans un dépôt interne et les paramètres définis pour ce dépôt le rendent accessible. Pour plus d’informations, consultez « Partage d’actions et de workflows au sein de votre entreprise."

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 « À propos 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 ou entreprise 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 ou l’entreprise du dépôt appelant, à condition que l’exécuteur ait été mis à la disposition du dépôt appelant

Limites

  • Les workflows réutilisables ne peuvent pas appeler d’autres workflows réutilisables.
  • Vous pouvez appeler un maximum de 20 workflows réutilisables à partir d’un fichier de workflow unique.
  • Les workflows réutilisables stockés dans un dépôt privé ne peuvent être utilisés que par les workflows au sein du même dépôt. * La propriété strategy n’est prise en charge dans aucun travail qui appelle un workflow réutilisable.
  • 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 ».
  • 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 ».

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.

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

    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 dépôt. 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 ».

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

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

Vous référencez des fichiers de workflow réutilisable en utilisant une des syntaxes suivantes :

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

{ref} peut être un SHA, une étiquette de mise en production ou un nom de branche. Le SHA de validation est le plus sûr pour la stabilité et la sécurité. Pour plus d’informations, consultez « Renforcement 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.

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

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

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.

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 "::set-output name=firstword::hello"
      - id: step2
        run: echo "::set-output name=secondword::world"

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 de sorties de travaux, consultez « Syntaxe de workflow pour GitHub Actions ».

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

  • 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 « 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 « Appel d’un workflow réutilisable ».

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 :

Étapes suivantes

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

Vous pouvez standardiser les déploiements en créant un groupe d’exécuteurs autohébergés qui peut uniquement exécuter un workflow réutilisable spécifique. Pour plus d’informations, consultez « Gestion de l’accès aux exécuteurs auto-hébergés à l’aide de groupes ».