Créer une action GitHub personnalisée

Effectué

GitHub Actions est une fonctionnalité puissante qui vous aide à aller du code au cloud, le tout avec le confort et le côté pratique de votre propre dépôt. Ici, vous allez découvrir les différents types d’actions GitHub, ainsi que les métadonnées, la syntaxe et les commandes de workflow pour créer des actions GitHub personnalisées.

Types d’actions GitHub

Les actions sont des tâches individuelles que vous pouvez utiliser pour personnaliser vos workflows de développement. Vous pouvez créer vos propres actions en écrivant du code personnalisé qui interagit avec votre dépôt pour effectuer des tâches personnalisées ou en utilisant des actions partagées par la communauté GitHub. En parcourant les différentes actions, vous pouvez noter qu’il existe trois types d’actions : les actions de conteneur Docker, les actions JavaScriptet les actions d’étape exécution composites. Examinons de plus près chaque type d’action :

Actions de conteneur Docker

Les conteneurs Docker empaquettent l’environnement avec le code GitHub Actions. Cela signifie que l’action s’exécute dans un environnement cohérent et fiable, car toutes ses dépendances se trouvent dans ce conteneur. Si l’action doit s’exécuter dans une configuration d’environnement spécifique, les conteneurs Docker sont un bon moyen de le faire, car vous pouvez personnaliser le système d’exploitation et les outils. L’inconvénient est que, étant donné que le travail doit créer et récupérer le conteneur, les actions du conteneur Docker sont souvent plus lentes que les actions JavaScript.

Avant de créer une action de conteneur Docker, vous devez avoir des connaissances de base sur la façon d’utiliser les variables d’environnement et le système de fichiers du conteneur Docker. Les étapes à suivre pour créer une action de conteneur Docker sont alors minimales et simples :

1. Créez un Dockerfile pour définir les commandes permettant d’assembler l’image Docker.
2. Créez un fichier de métadonnées action.yml pour définir les entrées et les sorties de l’action. Définissez la valeur de runs: using: sur docker et la valeur de runs: image: sur Dockerfile dans le fichier.
3. Créez un fichier entrypoint.sh pour décrire l’image docker.
4. Commitez et poussez (push) votre action dans GitHub avec les fichiers suivants : action.yml, entrypoint.sh, Dockerfile et README.md.

Actions JavaScript

Les actions JavaScript peuvent s’exécuter directement sur la machine de l’exécuteur et séparer le code de l’action de l’environnement qui est utilisé pour exécuter l’action. Pour cette raison, le code d’action est simplifié et peut s’exécuter plus rapidement que les actions au sein d’un conteneur Docker.

Comme prérequis à la création et à l’utilisation d’actions JavaScript empaquetées, vous devez télécharger Node.js, qui inclut npm. À titre d’étape facultative (mais que nous recommandons), vous pouvez utiliser GitHub Actions Toolkit Node.js, une collection de packages Node.js qui vous permet de créer rapidement des actions JavaScript avec davantage de cohérence.

Les étapes à suivre pour créer une action JavaScript sont alors minimales et simples :

1. Créez un fichier de métadonnées action.yml pour définir les entrées et les sorties de l’action, et indiquez à l’exécuteur de l’action comment démarrer l’exécution de cette action JavaScript.
2. Créez un fichier index.js avec les informations de contexte sur les packages Toolkit, le routage et d’autres fonctions de l’action.
3. Commitez et poussez votre action dans GitHub avec les fichiers suivants : action.yml, index.js, node_modules, package.json, package-lock.json et README.md.

Actions d’étapes d’exécution composites

Les actions d’étapes d’exécution composites vous permettent de réutiliser des actions en utilisant des scripts de shell. Vous pouvez même combiner plusieurs langages de shell au sein de la même action. Si vous avez un grand nombre de scripts de shell pour automatiser plusieurs tâches, vous pouvez désormais les transformer facilement en action et les réutiliser pour différents workflows. Il est parfois plus facile d’écrire simplement un script de shell que d’utiliser JavaScript ou d’encapsuler votre code dans un conteneur Docker.

Action composite empaquetée

Les actions composites empaquetées regroupent plusieurs étapes dans une unité réutilisable. Ces actions sont définies dans un référentiel et peuvent être référencées dans des flux de travail entre différents référentiels. L’empaquetage d’une action composite simplifie les flux de travail, réduit la duplication et améliore la facilité de maintenance.

Lors de la création d’une action composite empaquetée, les étapes sont définies dans un seul fichier action.yml. Ce fichier spécifie les entrées, les sorties et la séquence de commandes ou d’actions à exécuter. Les actions composites empaquetées sont particulièrement utiles pour automatiser des tâches répétitives ou combiner plusieurs commandes shell en une seule action réutilisable.

Créer une action composite

1. Configurer un répertoire pour l’action composite

Vous devez placer votre action composite dans son propre répertoire dans le référentiel.

Exemple de structure de répertoire :

.github/actions/my-composite-action/
├── action.yml
└── scripts/
    └── my-script.sh

2. Définir le fichier action.yml

Dans le répertoire my-composite-action, créez un fichier action.yml.

name: "My Composite Action"
description: "A reusable composite action that checks out code and sets up Node.js"

inputs:
  node-version:
    description: "The Node.js version to use"
    required: true

runs:
  using: "composite"
  steps:
    - name: Checkout repository
      uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}

Remarque : Le champ using : « composite » indique que cette action est une action composite.

3. Utiliser l’action composite dans un flux de travail

Une fois l’action composite créée, elle peut être référencée dans un workflow GitHub Actions.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Use my composite action
        uses: ./.github/actions/my-composite-action
        with:
          node-version: '18'

Si votre action composite est partagée à partir d’un autre référentiel, référencez-la comme suit :

uses: owner/repository/.github/actions/my-composite-action@v1

Ajouter des sorties à une action composite

Les actions composites peuvent définir des sorties que les flux de travail peuvent utiliser pour transmettre des données entre les étapes ou les travaux. Les sorties sont particulièrement utiles pour partager des résultats ou des valeurs calculées d’une action à une autre.

L’exemple suivant montre comment définir et utiliser une sortie dans une action composite :

Définir une sortie dans action.yml

Le fichier action.yml spécifie une sortie nommée script-result. Cette sortie récupère sa valeur à partir de la sortie result de l’étape run-script. L’étape run-script exécute une commande Bash pour définir la valeur de sortie.

outputs:
  script-result:
    description: "Result from the script"
    value: ${{ steps.run-script.outputs.result }}

runs:
  using: "composite"
  steps:
    - id: run-script
      run: echo "result=Success" >> $GITHUB_OUTPUT
      shell: bash

Utiliser la sortie dans un flux de travail

Une fois l’action composite créée, sa sortie est accessible dans un flux de travail. Voici un exemple :

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Run composite action
        id: my-action
        uses: ./.github/actions/my-composite-action

      - name: Display result
        run: echo "Script Result: ${{ steps.my-action.outputs.script-result }}"

Dans cet exemple :

• L’action composite est appelée à l’aide du mot clé uses.
• Accédez à la sortie script-result à l’aide de la syntaxe steps.<step-id>.outputs.<output-name>.
• Affichez le résultat dans les journaux de flux de travail.

Définissez des sorties dans des actions composites pour créer des flux de travail réutilisables et modulaires. Cette approche simplifie le partage de données et améliore la facilité de maintenance.

Meilleures pratiques pour les actions composites

Bonne pratique	Description
Utiliser le contrôle de version	Utilisez une balise v1 pour référencer la version 1 stable.
Conserver les actions modulaires	Regroupez les étapes associées à l’intérieur d’une action composite.
Entrées de document et sorties	Ajoutez des descriptions pour les entrées/sorties dans action.yml.
Tester avant la publication	Validez l’action composite dans un référentiel de test.

Action composite dans un flux de travail

Les actions composites constituent un moyen puissant de simplifier les flux de travail en regroupant plusieurs étapes dans une unité réutilisable. Ces actions vous permettent de définir une séquence de commandes ou d’actions dans un seul fichier action.yml, ce qui facilite la maintenance et la réutilisation de la logique entre les flux de travail.

Avantages des actions composites :

• Réutilisabilité : définissez des actions une fois et utilisez-les dans plusieurs flux de travail.
• Facilité de maintenance : réduisez la duplication en centralisant la logique dans une seule action.
• Modularité : combinez plusieurs commandes d’interpréteur de commandes ou d’autres actions en une seule unité.

Développer une action pour configurer une interface CLI sur les exécuteurs GitHub Actions

De nombreux flux de travail CI/CD nécessitent une version spécifique d’un outil CLI pour interagir avec les services cloud, gérer l’infrastructure ou exécuter des scripts. Bien que les exécuteurs hébergés par GitHub soient préinstallés avec de nombreux outils, ils peuvent ne pas inclure la version exacte dont votre flux de travail a besoin, en particulier s’il s’agit d’une version antérieure ou non prise en charge. Au lieu d’installer la version CLI requise dans chaque workflow, vous pouvez créer une action GitHub réutilisable qui :

• Garantit une installation cohérente de la version cli requise entre les travaux.
• Simplifie les flux de travail en centralisant la logique d’installation.
• Optimise la mise en cache pour accélérer l’exécution du flux de travail.

Comment développer une action de configuration CLI

Une action de configuration CLI est une action basée sur JavaScript qui installe et configure une interface CLI sur un exécuteur GitHub.

Étapes de création de l’action :

Étape 1 : Configurer le répertoire d’actions

Pour créer manuellement le répertoire de votre action de configuration cli, procédez comme suit :

1. Accédez à votre référentiel

2. Créer un répertoire pour l’action
   Créez un répertoire nommé my-cli-action dans le dossier .github/actions. Cela garantit que votre action est organisée et suit la structure recommandée de GitHub pour les actions personnalisées.

3. Accédez au nouveau répertoire
   Accédez au répertoire nouvellement créé pour commencer à ajouter des fichiers pour votre action :

4. Vérifiez la structure de répertoires
   Après avoir créé le répertoire, votre structure de référentiel doit ressembler à ceci :

your-repository/
├── .github/
│   ├── actions/
│   │   ├── my-cli-action/

Vous êtes maintenant prêt à poursuivre la création du fichier action.yml et d’autres fichiers nécessaires pour votre action de configuration CLI.

Étape 2 : Définir le fichier de métadonnées action.yml

Créez un fichier action.yml pour décrire l’action.

name: "Setup MyCLI"
description: "Installs MyCLI and adds it to the PATH"
author: "Your Name"

inputs:
  version:
    description: "The CLI version to install"
    required: false
    default: "latest"

runs:
  using: "node16"
  main: "index.js"

Pourquoi utiliser : node16 ? Cette action exécute du code JavaScript à l’aide de Node.js 16.

Étape 3 : Créer un script JavaScript pour installer l’interface CLI

Dans le même répertoire, créez un fichier nommé index.js et ajoutez le code suivant :

const core = require('@actions/core');
const { execSync } = require('child_process');

async function run() {
  try {
    const version = core.getInput('version') || 'latest';
    
    console.log(`Installing MyCLI version: ${version}...`);

    execSync(`curl -fsSL https://cli.example.com/install.sh | sh`, { stdio: 'inherit' });

    console.log("MyCLI installed successfully.");
  } catch (error) {
    core.setFailed(`Installation failed: ${error.message}`);
  }
}

run();

Le code JavaScript ci-dessus utilise core.getInput() pour récupérer la version CLI spécifiée comme entrée. Il exécute ensuite une commande curl pour télécharger et installer l’interface CLI. Si le processus d’installation échoue, l’action utilise core.setFailed() pour marquer le flux de travail comme ayant échoué.

Étape 4 : Tester l’action localement

Avant d’utiliser l’action dans un flux de travail, testez-la sur un exécuteur hébergé par GitHub.
Créez un fichier de flux de travail (.github/workflows/test.yml) dans votre référentiel :

name: Test MyCLI Setup

on:
  push:
    branches:
      - main
      - feature/*

1. Déclenchement du flux de travail
Le flux de travail est déclenché sur les envois (push) vers la branche principale et toute branche correspondant au modèle de fonctionnalité/*. Vous pouvez l’ajuster pour qu’il corresponde à la stratégie de branchement de votre référentiel.

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

2. Cloner le référentiel
L’action actions/checkout@v4 est utilisée pour cloner le référentiel sur l’exécuteur. Cela garantit que le flux de travail a accès aux fichiers du référentiel.

      - name: Install MyCLI
        uses: ./.github/actions/my-cli-action
        with:
          version: '1.2.3'

3. Exécuter l’action personnalisée
La ligne uses: ./.github/actions/my-cli-action fait référence localement à l’action personnalisée. Vérifiez que le répertoire d’actions et le fichier action.yml sont correctement configurés. L’entrée de version spécifie la version CLI à installer, dans ce cas version 1.2.3.

      - name: Verify CLI Installation
        run: |
          echo "Checking MyCLI version..."
          mycli --version

4. Vérifier l’installation de l’interface CLI
Cette étape exécute une commande shell pour vérifier que l’interface CLI a été installée correctement. Il vérifie la version de l’interface CLI installée en exécutant mycli --version.

Tester localement

Pour tester ce flux de travail localement, utilisez l’outil CLI act :

act -j test

Cela simule l’environnement GitHub Actions sur votre ordinateur local, ce qui vous permet de déboguer et de valider le flux de travail avant d’envoyer des modifications.

Conseil d’optimisation : mise en cache

Pour améliorer les performances du flux de travail, cachez le répertoire d’installation de l’interface CLI à l’aide de l’action actions/cache :

      - name: Cache MyCLI
        uses: actions/cache@v4
        with:
          path: ~/.mycli
          key: mycli-${{ runner.os }}-${{ inputs.version }}

Cela garantit que les exécutions suivantes réutilisent l’installation de l’interface CLI mise en cache, ce qui réduit le temps d’installation.

Meilleures pratiques pour les actions d’installation de l’interface CLI

Meilleure pratique	Description
Utiliser le contrôle de version	Autorisez les utilisateurs à spécifier une version CLI via inputs.version.
Gérer correctement les erreurs	Utilisez core.setFailed() pour quitter les erreurs.
Cache CLI Installation	Optimisez les performances du flux de travail à l’aide de actions/cache.
Fournir une documentation	Expliquer l’utilisation et les entrées dans README.md.

Résoudre les problèmes liés aux actions JavaScript

Lorsque vous utilisez GitHub Actions basé sur JavaScript, vous pouvez rencontrer un comportement inattendu, des erreurs ou des échecs lors de l’exécution du flux de travail. Cette unité fournit des techniques et des outils pour vous aider à identifier et résoudre les problèmes dans vos actions JavaScript.

Scénarios courants de résolution des problèmes

Problème	Cause potentielle	Correctif suggéré
L’action échoue avec une trace	Erreur de syntaxe ou d’exécution dans index.js	Utiliser console.log() et vérifier les journaux d’activité
Les entrées sont undefined	Nom d’entrée incorrect ou entrée manquante	Vérifier action.yml et la manière dont les entrées sont passées
Variables d’environnement non définies	core.exportVariable ou process.env non utilisé correctement	Passez en revue le paramètre de code des variables
Fichier introuvable	Chemins relatifs manquants	Utiliser __dirname ou utiliser des chemins d’accès complets aux fichiers
Le cache n’est pas restauré	Valeurs de key ou de path incorrectes	Vérifier la configuration et les clés du cache

Utiliser la journalisation pour le débogage

Journaliser les messages avec core.info, core.debuget console.log

const core = require('@actions/core');

core.info("This is an info message");
core.debug("This is a debug message");
console.log("This is a raw console log");

✅ Utilisez core.debug pour les journaux de débogage. Ceux-ci s’affichent uniquement lorsque ACTIONS_STEP_DEBUG a la valeur true.

Activer la journalisation du débogage

Vous pouvez activer les journaux de débogage au niveau de l’étape en définissant le secret suivant :

ACTIONS_STEP_DEBUG=true

Pour activer les journaux de diagnostic de l’exécuteur, définissez :

ACTIONS_RUNNER_DEBUG=true

Définir des secrets pour le débogage

1. Accédez à votre dépôt GitHub.
2. Accédez à Paramètres>Secrets et variables>Actions.
3. Ajoutez de nouveaux secrets avec les noms et valeurs suivants :
   • ACTIONS_STEP_DEBUG : true
   • ACTIONS_RUNNER_DEBUG : true

Inspecter les journaux de flux de travail

En cas d’échec d’un flux de travail, cliquez sur le travail ayant échoué sous l’onglet Actions. Développez chaque étape pour :

• Voir les journaux détaillés
• Vérifier la sortie standard (stdout)
• Voir le code de sortie des scripts
• Identifier les exceptions non gérées

🔍 Exemple de sortie du journal

Error: Cannot find module '@actions/core'
Require stack:
- /home/runner/work/_actions/my-org/my-action/index.js

✅ Correctif : Exécutez l’installation @actions/core et la validation de npm node_modules (ou utilisez ncc pour regrouper l’action).

Tester votre action localement

Utiliser l’acte : un outil CLI pour exécuter GitHub Actions localement. Exemple:

act -j test

🛠 Veillez à simuler correctement votre environnement GitHub lors du test local.

Gérer correctement les erreurs

Intercepter les exceptions et les échecs avec des messages utiles :

try {
  // your logic
} catch (error) {
  core.setFailed(`Action failed with error: ${error.message}`);
}

🔁 Cela garantit que GitHub arrête le flux de travail en cas d’erreur et fournit des journaux lisibles.

Meilleures pratiques pour le débogage d’actions JavaScript

Pratique	Description
Utiliser core.debug()	Masquer les journaux d’activité détaillés, sauf si le débogage est activé.
Valider action.yml	Vérifiez que les entrées et sorties sont correctement définies.
Code groupé	Utilisez @vercel/ncc pour compiler JavaScript dans un seul fichier. Cela réduit les dépendances et garantit que tous les modules requis sont inclus, ce qui empêche les erreurs d’exécution provoquées par des fichiers manquants.
Tester avec ACT	Simuler des exécutions localement pour des itérations plus rapides.
Utiliser try/catch	Empêchez les flux de travail de échouer en mode silencieux.

Résoudre les problèmes liés aux actions de conteneur Docker

Les actions de conteneur Docker sont puissantes pour encapsuler des outils et des environnements complexes dans les flux de travail GitHub Actions. Toutefois, le débogage de ces actions peut être plus difficile que les actions JavaScript en raison de leur environnement d’exécution isolé. Cette unité vous guide tout au long de l’identification, du diagnostic et de la résolution des problèmes liés aux actions docker.

Problèmes courants dans les actions de conteneur Docker

Problème	La cause	Correctif suggéré
Échec du démarrage de l’action	ENTRYPOINT ou CMD mal configuré	Confirmer que Dockerfile utilise ENTRYPOINT correctement
Dépendances manquantes	Dépendances non installées ou mal configurées	Vérifier que tous les packages sont installés dans l’image
Entrées non reçues	INPUT_ variables d’environnement non accessibles	Utiliser process.env.INPUT_<INPUT_NAME> (ou équivalent à l’interpréteur de commandes)
Fichier introuvable	Chemin d’accès de fichier incorrect à l’intérieur du conteneur	Utiliser des chemins absolus ou valider une structure de répertoires
Autorisation refusée	Le fichier ou le script ne dispose pas de l’autorisation d’exécution	Ajouter RUN chmod +x <script> dans Dockerfile
Échecs liés au réseau	Services externes non accessibles	Valider les paramètres réseau et la logique de nouvelle tentative

Comprendre le cycle de vie de l’action Docker

Avant de résoudre les problèmes, il est utile de comprendre comment les actions de conteneur Docker s’exécutent.

1. Déclencheur de flux de travail

Un flux de travail GitHub Actions commence en réponse à un événement configuré, tel qu’un push, pull_requestou manuel workflow_dispatch.

2. Configuration de l’exécuteur

GitHub provisionne une nouvelle machine virtuelle (l’exécuteur) pour exécuter le flux de travail. L’exécuteur prépare l’environnement en téléchargeant les définitions d’action et en résolvant les dépendances.

3. Résolution d’action

Si l’action spécifie runs.using: docker dans son fichier action.yml, GitHub la reconnaît comme une action docker.

4. Génération ou extraction d’images

GitHub génère l’image Docker définie dans les données Dockerfile de l’action ou extrait une image prédéfinie si elle est spécifiée. Cette image définit l’environnement dans lequel le code d’action s’exécute.

5. Exécution du conteneur

L’exécuteur lance le conteneur Docker, monte l’espace de travail et injecte des variables d’environnement, y compris les secrets et les entrées définis dans le flux de travail.

6. Exécutions de points d’entrée

GitHub exécute la commande entrypoint à partir du fichier Dockerfile à l’intérieur du conteneur. C’est là que la logique d’action personnalisée s’exécute, généralement un script ou une application.

7. Gestion des résultats

Toutes les sorties définies par l’action conteneur sont capturées par l’exécuteur et transmises aux étapes suivantes du flux de travail. Une fois terminé, le conteneur s’arrête et l’exécuteur est ignoré.

Remarque : les actions de conteneur Docker s’exécutent dans un environnement propre et isolé. L’état du système de fichiers, les outils installés et les variables d’environnement doivent tous être définis dans le fichier Dockerfile.

Techniques de débogage

1. Ajouter la journalisation

Utilisez des instructions echo, printf ou logging dans votre script de point d’entrée :

echo "Starting Docker action..."
echo "Input VALUE: $INPUT_VALUE"

Consignez toutes les entrées et étapes critiques pour diagnostiquer l’endroit où se produit l’échec.

2. Générer et tester localement

Utilisez Docker sur votre ordinateur pour simuler le comportement du conteneur :

docker build -t my-action .
docker run -e INPUT_NAME=value my-action

Assurez-vous que les variables d’environnement imitent les ensembles GitHub.

3. Utiliser l’interface CLI d’action pour simuler des flux de travail GitHub

Installez l’action pour exécuter vos flux de travail GitHub localement :

act -j test-job

Idéal pour tester les actions Docker dans les flux de travail sans envoyer (push) vers GitHub.

4. Valider la configuration de Dockerfile

Vérifiez que vous définissez ENTRYPOINT ou CMD. Copiez vos scripts dans l’image et accordez-leur l’autorisation d’exécution :

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]

5. Inspecter les journaux GitHub

Cliquez sur une exécution de flux de travail ayant échoué, développez chaque étape et examinez :

• Journaux d’activité de build Docker
• Sortie standard et erreur standard du conteneur
• Codes de sortie et traces de pile 🔍 Les journaux révèlent souvent des packages manquants, des erreurs de syntaxe ou des problèmes d’autorisations.

Exemple : Erreur de point d’entrée

Error: container_linux.go:380: starting container process caused "exec: \"/entrypoint.sh\": permission denied"

✅ Correctif : Ajoutez RUN chmod +x /entrypoint.sh dans votre fichier Dockerfile.

Correspondances des variables d’environnement

Entrée GitHub	Variable d’environnement Docker
with: name: test	INPUT_NAME=test
GITHUB_WORKSPACE	Mappé dans /github/workspace
GITHUB_EVENT_NAME	Événement qui a déclenché le flux de travail

echo "Input was $INPUT_NAME"
echo "Working dir: $GITHUB_WORKSPACE"

Utiliser la résolution des problèmes liés aux secrets

Activez la journalisation supplémentaire en ajoutant ces secrets à votre dépôt ou organisation :

Secret	Descriptif
ACTIONS_STEP_DEBUG	Active la journalisation du débogage
ACTIONS_RUNNER_DEBUG	Active les diagnostics de l’exécuteur

Meilleures pratiques pour le débogage d’actions Docker

Bonne pratique	Pourquoi
Utiliser la journalisation généreusement	Aide à tracer les points d’échec
Toujours définir chmod +x	Éviter les erreurs d’autorisation sur les scripts shell
Valider les entrées dans votre script	Intercepter les entrées manquantes ou incorrectes tôt
Réduire les dépendances de conteneur	Les images plus petites sont plus faciles à déboguer
Tester localement avec docker exécuter ou agir	Itérations plus rapides et commentaires immédiats