Réutiliser des workflows

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.

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

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 en utilisant secrets: inherit dans le flux de travail appelant, vous pouvez y faire référence même s'ils ne sont pas explicitement définis dans la clé on. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».
```
jobs:
  reusable_workflow_job:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/labeler@v4
      with:
        repo-token: ${{ secrets.personal_access_token }}
        configuration-path: ${{ inputs.config-path }}
```
Dans l’exemple ci-dessus, personal_access_token est un secret défini au niveau du référentiel ou de l’organisation.

Avertissement

Les secrets d’environnement ne peuvent pas être transmis à partir du flux de travail car on.workflow_call ne prend pas en charge le mot clé environment. Si vous incluez environment dans le workflow réutilisable au niveau de la tâche, le secret d’environnement sera utilisé et non le secret transmis à partir du workflow de l’appelant. Pour plus d’informations, consultez « Gestion des environnements pour le déploiement » et « Workflow syntax for GitHub Actions ».
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:
      personal_access_token: ${{ secrets.token }}
```
Les flux de travail qui appellent des flux de travail 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 }}

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 référentiels 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 « Informations de référence sur l’utilisation sécurisée ».

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

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

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

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

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:
      personal_access_token: ${{ secrets.token }}

Les flux de travail qui appellent des flux de travail 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 « Exécution de variantes de tâches dans un workflow ».

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:
  ReusableMatrixJobForDeployment:
    strategy:
      matrix:
        target: [dev, stage, prod]
    uses: octocat/octo-repo/.github/workflows/deployment.yml@main
    with:
      target: ${{ matrix.target }}

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

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.yml → called-workflow-1.yml → called-workflow-2.yml → called-workflow-3.yml. Les boucles ne sont pas autorisées dans l’arborescence de workflows.

Remarque

Les flux de travail réutilisables imbriqués exigent que tous les flux de travail de la chaîne soient accessibles à l’appelant, et les autorisations ne peuvent être que conservées ou réduites (et non augmentées) tout au long de la chaîne. Pour plus d’informations, consultez « Référence des flux de travail réutilisables ».

À 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

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éutiliser 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:
      repo-token: ${{ secrets.personal_access_token }} # pass just this secret

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 flux de travail réutilisable achevé avec succès définit une chaîne vide pour sa sortie et que l'avant-dernier flux de travail réutilisable achevé avec succès définit une valeur réelle pour sa sortie, la sortie contiendra la valeur de l'avant-dernier flux de travail réutilisable achevé.

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.

La valeur value doit être définie sur une sortie au niveau du travail dans le flux de travail appelé. Les sorties au niveau de l’étape doivent d’abord être mappées aux sorties au niveau du travail, comme indiqué ci-dessous.

Pour plus d’informations, consultez « Transmission d’informations entre les travaux » et « Workflow syntax for GitHub Actions ».

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

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

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 « Store and share data with workflow artifacts ».

Monitoring des workflows en cours d’utilisation

Les organisations qui utilisent GitHub Enterprise Cloud peuvent interagir avec le journal d’audit via l’API REST GitHub pour surveiller les flux de travail utilisés. Pour plus d’informations, consultez la documentation GitHub Enterprise Cloud.

Étapes suivantes

Pour plus d’informations sur les subtilités de la réutilisation des flux de travail, consultez Référence des flux de travail réutilisables.

Dans cet article