Utilisation de blocs élémentaires pré-écrits dans votre workflow

Vue d’ensemble

Vous pouvez utiliser des blocs élémentaires pré-écrits, appelés actions, dans votre workflow. Une action est un ensemble prédéfini et réutilisable de tâches ou de codes qui exécutent des tâches spécifiques dans le cadre d’un workflow.

Les actions peuvent être :

• Réutilisable : les actions peuvent être utilisées dans différents workflows et référentiels, ce qui vous permet d’éviter de réécrire le même code.
• Pré-écrit : de nombreuses actions sont disponibles dans le GitHub Marketplace, couvrant un large éventail de tâches telles que la vérification du code, la configuration d’environnements, l’exécution de tests et le déploiement d’applications.
• Configurable : vous pouvez configurer les actions avec des entrées, des sorties et des variables d’environnement pour les adapter à vos besoins spécifiques.
• Géré par la communauté : vous pouvez créer vos propres actions et les partager avec d’autres ou utiliser des actions développées par la communauté.

Les actions que vous utilisez dans votre workflow peuvent être définies dans :

• Le même dépôt que votre fichier de workflow
• Tout dépôt public
• Une image conteneur Docker publiée sur Docker Hub

GitHub Marketplace est un emplacement central où vous trouverez les actions créées par la communauté GitHub. La page GitHub Marketplace vous permet de filtrer les actions par catégorie.

Parcourir les actions de la Place de marché dans l’éditeur de workflow

Vous pouvez rechercher des actions et les parcourir directement dans l’éditeur de workflow de votre dépôt. Dans la barre latérale, vous pouvez rechercher une action spécifique, afficher les actions proposées et parcourir les catégories proposées. Vous pouvez également afficher le nombre d’étoiles qu’une action a reçues de la communauté GitHub.

1. Dans votre dépôt, accédez au fichier de workflow que vous souhaitez modifier.
2. En haut à droite de la vue des fichiers, pour ouvrir l’éditeur de workflow, cliquez sur .
   
3. À droite de l’éditeur, utilisez la barre latérale GitHub Marketplace pour parcourir les actions. Les actions avec le badge indiquent que GitHub a vérifié que le créateur de l’action est une organisation partenaire.
   

Ajout d’une action à votre workflow

Vous pouvez ajouter une action à votre workflow en référençant l’action dans votre fichier de workflow.

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

Ajout d’une action depuis GitHub Marketplace

La page de référencement d’une action inclut la version de l’action et la syntaxe de workflow requises pour utiliser l’action. Pour maintenir votre workflow stable même lorsque des mises à jour sont apportées à une action, vous pouvez référencer la version de l’action à utiliser en spécifiant le numéro d’étiquette Git ou Docker dans votre fichier de workflow.

1. Accédez à l’action que vous souhaitez utiliser dans votre workflow.
2. Cliquez pour afficher la liste complète de la Place de marché pour l’action.
3. Sous « Installation », cliquez sur pour copier la syntaxe du workflow.
   
4. Collez la syntaxe en tant que nouvelle étape dans votre workflow. Pour plus d’informations, consultez « Workflow syntax for GitHub Actions ».
5. Si l’action vous oblige à fournir des entrées, définissez-les dans votre workflow. Pour obtenir des informations sur les entrées qu’une action peut nécessiter, consultez « Utilisation de blocs élémentaires pré-écrits dans votre workflow ».

Vous pouvez également activer Dependabot version updates pour les actions que vous ajoutez à votre workflow. Pour plus d’informations, consultez « Maintenir vos actions à jour avec Dependabot ».

Ajout d’une action à partir du même dépôt

Si une action est définie dans le même dépôt que celui où votre fichier de workflow utilise l’action, vous pouvez référencer l’action avec la syntaxe {owner}/{repo}@{ref} ou ./path/to/dir dans votre fichier de workflow.

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

Le fichier action.yml est utilisé pour fournir des métadonnées pour l’action. Découvrez le contenu de ce fichier dans « Metadata syntax for GitHub Actions ».

Ajout d’une action à partir d’un autre dépôt

Si une action est définie dans un autre dépôt que celui de votre fichier de workflow, vous pouvez référencer l’action avec la syntaxe {owner}/{repo}@{ref} dans votre fichier de workflow.

L’action doit être stockée dans un dépôt public.

jobs:
  my_first_job:
    steps:
      - name: My first step
        uses: actions/setup-node@v4

Référencement d’un conteneur sur Docker Hub

Si une action est définie dans une image conteneur Docker publiée sur Docker Hub, vous devez référencer l’action avec la syntaxe docker://{image}:{tag} dans votre fichier de workflow. Pour protéger votre code et vos données, nous vous recommandons vivement de vérifier l’intégrité de l’image conteneur Docker à partir de Docker Hub avant de l’utiliser dans votre workflow.

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

Pour obtenir des exemples d’actions Docker, consultez le workflow Docker-image.yml et « Creating a Docker container action ».

Renforcement de la sécurité pour l’utilisation d’actions dans vos flux de travail

GitHub fournit des fonctionnalités de sécurité que vous pouvez utiliser pour augmenter la sécurité de vos flux de travail. Vous pouvez utiliser les fonctionnalités intégrées GitHub pour vous assurer que vous êtes informé des vulnérabilités dans les actions que vous consommez ou pour automatiser le processus d’actualisation des actions dans vos flux de travail. Pour plus d’informations, consultez « Utiliser les fonctions de sécurité de GitHub pour sécuriser votre utilisation des actions GitHub ».

Utilisation de la gestion des mises en production pour vos actions personnalisées

Les créateurs d’une action de communauté ont la possibilité d’utiliser des étiquettes, des branches ou des valeurs SHA pour gérer les mises en production de l’action. Comme pour toute dépendance, vous devez indiquer la version de l’action que vous souhaitez utiliser en fonction de votre confort avec l’acceptation automatique des mises à jour de l’action.

Vous désignerez la version de l’action dans votre fichier de workflow. Consultez la documentation de l’action pour obtenir des informations sur son approche de la gestion des mises en production et pour voir quelle balise, branche ou valeur SHA utiliser.

Utilisation des étiquettes

Les étiquettes sont utiles pour vous permettre de décider quand basculer entre les versions principales et mineures, mais elles sont plus éphémères et peuvent être déplacées ou supprimées par le chargé de maintenance. Cet exemple montre comment cibler une action étiquetée v1.0.1 :

steps:
  - uses: actions/javascript-action@v1.0.1

Utilisation des valeurs SHA

Si vous avez besoin d’un contrôle de versions plus fiable, vous devez utiliser la valeur SHA associée à la version de l’action. Les valeurs SHA sont immuables et, par conséquent, plus fiables que les étiquettes ou les branches. Toutefois, cette approche signifie que vous ne recevrez pas automatiquement les mises à jour pour une action, y compris les mises à jour de sécurité et les correctifs de bogues importants. Vous devez utiliser la valeur SHA complète d’un commit et non une valeur abrégée. Lorsque vous sélectionnez un SHA, vous devez vérifier qu’il provient du dépôt de l’action et non d’une fourche de dépôt. Cet exemple cible le SHA d’une action :

steps:
  - uses: actions/javascript-action@a824008085750b8e136effc585c3cd6082bd575f

Utilisation des branches

La spécification d’une branche cible pour l’action signifie qu’elle exécutera toujours la version figurant actuellement sur cette branche. Cette approche peut créer des problèmes si une mise à jour de la branche inclut des changements cassants. Cet exemple cible une branche nommée @main :

steps:
  - uses: actions/javascript-action@main

Pour plus d’informations, consultez « À propos des actions personnalisées ».

Utilisation d’entrées et de sorties avec une action

Une action accepte ou nécessite souvent des entrées et génère des sorties que vous pouvez utiliser. Par exemple, une action peut exiger que vous spécifiiez un chemin d’accès à un fichier, le nom d’une étiquette ou d’autres données qu’elle utilisera dans le cadre du traitement de l’action.

Pour afficher les entrées et sorties d’une action, vérifiez action.yml ou action.yaml dans le répertoire racine du dépôt.

Dans cet exemple de fichier action.yml, le mot clé inputs définit une entrée obligatoire appelée file-path et inclut une valeur par défaut qui sera utilisée si aucune valeur n’est spécifiée. Le mot clé outputs définit une sortie appelée results-file, qui vous indique où localiser les résultats.

name: "Example"
description: "Receives file and generates output"
inputs:
  file-path: # id of input
    description: "Path to test script"
    required: true
    default: "test-file.js"
outputs:
  results-file: # id of output
    description: "Path to results file"

Étapes suivantes

Pour continuer à découvrir GitHub Actions, consultez « Comprendre GitHub Actions ».