Personnaliser votre workflow à l’aide de variables d’environnement et de données d’artefact

  • 12 minutes

Vous allez voir ici comment utiliser les variables d’environnement par défaut et personnalisées, les scripts personnalisés, les dépendances de cache, et comment passer des données d’artefact entre différents travaux. Vous allez également voir comment accéder aux journaux de workflow à partir du site web GitHub et des points de terminaison de l’API REST.

Contextes et variables d’environnement par défaut

Dans le workflow GitHub Actions, il existe plusieurs variables d’environnement par défaut que vous pouvez utiliser, mais uniquement dans l’exécuteur qui exécute le travail. Ces variables par défaut respectent la casse et font référence aux valeurs de configuration du système et de l’utilisateur actuel. Nous vous recommandons d’utiliser ces variables d’environnement par défaut pour référencer le système de fichiers plutôt que d’utiliser des chemins de fichier codés en dur. Pour utiliser une variable d’environnement par défaut, spécifiez $, suivi du nom de la variable d’environnement.

jobs:
  prod-check:
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

En plus des variables d’environnement par défaut, vous pouvez utiliser des variables définies en tant que contextes. Les contextes et les variables par défaut sont similaires en ce sens qu’ils fournissent tous deux un accès aux informations d’environnement. Toutefois, ils présentent des différences importantes. Alors que les variables d’environnement par défaut ne peuvent être utilisées que dans l’exécuteur, les variables de contexte peuvent être utilisées à n’importe quel endroit du workflow. Par exemple, les variables de contexte vous permettent d’exécuter une instruction if pour évaluer une expression avant le démarrage de l’exécuteur.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying to production server on branch $GITHUB_REF"

Cet exemple utilise le contexte github.ref pour vérifier la branche qui a déclenché le workflow. S’il s’agit de la branche main, l’exécuteur est lancé et affiche le message « Deploying to production server on branch $GITHUB_REF » (Déploiement sur le serveur de production de la branche $GITHUB_REF). La variable d’environnement par défaut $GITHUB_REF est utilisée dans l’exécuteur pour référencer la branche. Notez que les variables d’environnement par défaut sont toutes en majuscules, alors que les variables de contexte sont en minuscules.

Variables d’environnement personnalisées

Vous pouvez utiliser des variables d’environnement personnalisées dans votre fichier de workflow de la même façon que vous utilisez les variables d’environnement par défaut. Pour créer une variable personnalisée, vous devez la définir dans votre fichier de workflow à l’aide du contexte env. Si vous souhaitez utiliser la valeur d’une variable d’environnement à l’intérieur d’un exécuteur, vous pouvez utiliser la méthode habituelle du système d’exploitation exécuteur pour lire les variables d’environnement.

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Nice work, $First_Name. Deploying to production server on branch $GITHUB_REF"
        env:
          First_Name: Mona

Scripts de votre workflow

Dans les exemples d’extraits de code de workflow précédents, le mot clé run est utilisé pour afficher une chaîne de texte. Étant donné que le mot clé run indique au travail d’exécuter une commande dans l’exécuteur, vous devez utiliser le mot clé run pour exécuter des actions ou des scripts.

jobs:
  example-job:
    steps:
      - run: npm install -g bats

Dans cet exemple, vous utilisez npm pour installer le package de tests logiciels bats avec le mot clé run. Vous pouvez également exécuter un script en tant qu’action. Vous pouvez stocker le script dans votre dépôt, ce qui se fait souvent dans un répertoire .github/scripts/, puis fournir le chemin et le type de shell à l’aide du mot clé run.

jobs:
  example-job:
    steps:
      - name: Run build script
        run: ./.github/scripts/build.sh
        shell: bash

Mettre en cache les dépendances avec l’action de cache

Lorsque vous créez un workflow, il est fréquent d’avoir besoin de réutiliser les mêmes sorties ou de télécharger les dépendances d’une exécution à l’autre. Au lieu de télécharger ces dépendances à chaque fois, vous pouvez les mettre en cache pour que votre workflow s’exécute plus rapidement et plus efficacement. Cela peut réduire considérablement le temps nécessaire à l’exécution de certaines étapes du workflow, car les travaux exécutés sur les exécuteurs hébergés sur GitHub démarrent à chaque fois dans un environnement virtuel propre. La mise en cache des dépendances permet d’accélérer le temps nécessaire pour recréer ces fichiers de dépendance.

Pour mettre en cache les dépendances d’un travail, utilisez l’action cache de GitHub. Cette action permet de récupérer un cache identifié par une clé unique que vous fournissez. Lorsque l’action trouve le cache, elle récupère les fichiers mis en cache dans le chemin que vous avez configuré. Pour utiliser l’action cache, vous devez définir quelques paramètres spécifiques :

Paramètre Description Obligatoire
Clé : Fait référence à l’identificateur de clé créé lors de l’enregistrement et de la recherche d’un cache. Oui
Chemin d’accès Fait référence au chemin de fichier de l’exécuteur à mettre en cache ou à rechercher. Oui
Restore-keys Se compose d’autres clés de cache existantes si la clé de cache souhaitée est introuvable. No 
steps:
  - uses: actions/checkout@v2

  - name: Cache NPM dependencies
    uses: actions/cache@v2
    with:
      path: ~/.npm
      key: ${{ runner.os }}-npm-cache-${{ hashFiles('**/package-lock.json') }}
      restore-keys: |
        ${{ runner.os }}-npm-cache-

Dans l’exemple précédent, path est défini sur ~/.npm, et key comprend le système d’exploitation de l’exécuteur ainsi que le hachage SHA-256 du fichier package-lock.json. Il est utile de préfixer la clé avec un ID (npm-cache dans cet exemple) lorsque vous utilisez le restore-keys de secours et que vous avez plusieurs caches.

Passer des données d’artefact d’un travail à un autre

Dans la même idée que de mettre en cache des dépendances dans votre workflow, vous pouvez passer des données entre les différents travaux d’un même workflow. Pour ce faire, vous pouvez utiliser les actions upload-artifact et download-artifact. Les travaux qui dépendent des artefacts d’un travail précédent doivent attendre que le travail précédent se termine correctement avant de pouvoir s’exécuter. C’est utile si vous avez une série de travaux qui doivent s’exécuter de façon séquentielle en fonction des artefacts qui ont été chargés à partir d’un travail précédent. Par exemple, job_2 exige job_1 à l’aide de la syntaxe needs: job_1.

name: Share data between jobs
on: push
jobs:
  job_1:
    name: Upload File
    runs-on: ubuntu-latest
    steps:
      - run: echo "Hello World" > file.txt
      - uses: actions/upload-artifact@v2
        with:
          name: file
          path: file.txt

  job_2:
    name: Download File
    runs-on: ubuntu-latest
    needs: job_1
    steps:
      - uses: actions/download-artifact@v2
        with:
          name: file
      - run: cat file.txt

L’exemple précédent comprend deux travaux. job_1 écrit du texte dans le fichier file.txt, puis il utilise l’action actions/upload-artifact@v2 pour charger cet artefact et stocker les données en vue d’une utilisation ultérieure dans le workflow. job_2 exige que job_1 se termine à l’aide de la syntaxe needs: job_1, puis utilise l’action actions/download-artifact@v2 pour télécharger cet artefact, et affiche le contenu de file.txt.

Activer la journalisation du débogage pour les étapes dans un workflow

Dans certains cas, les journaux de workflow par défaut ne fournissent pas suffisamment de détails pour comprendre l’échec d’une exécution, d’un travail ou d’une étape de workflow. Dans ces cas, vous pouvez activer une journalisation supplémentaire pour deux options : exécutionsétapes. Activez cette journalisation de diagnostic en définissant deux secrets de dépôt qui nécessitent que l’accès admin au dépôt soit défini sur true :

  • Si vous souhaitez activer la journalisation des diagnostics pour les exécutions, définissez le secret ACTIONS_RUNNER_DEBUG sur la valeur true dans le dépôt qui contient le workflow.
  • Si vous souhaitez activer la journalisation des diagnostics pour les étapes, définissez le secret ACTIONS_STEP_DEBUG sur la valeur true dans le dépôt qui contient le workflow.

Accéder aux journaux de workflow à partir de l’interface utilisateur

Dans une automatisation réussie, vous passez le moins de temps possible à examiner ce qui est automatisé afin de pouvoir vous concentrer sur ce qui est important. Mais parfois, les choses ne se passent pas comme prévu, et vous devez examiner ce qui s’est passé. Ce processus de débogage peut être frustrant. Toutefois, GitHub fournit une structure d’affichage claire qui permet de naviguer rapidement entre les travaux, tout en conservant le contexte de l’étape de débogage en cours. Pour voir les journaux d’une exécution de workflow dans GitHub, vous pouvez suivre les étapes ci-dessous :

  1. Accédez à l’onglet Actions de votre dépôt.
  2. Dans la barre latérale de gauche, cliquez sur le workflow de votre choix.
  3. Dans la liste des exécutions de workflow, sélectionnez l’exécution souhaitée.
  4. Sous Jobs (Travaux), sélectionnez le travail souhaité.
  5. Consultez la sortie du journal.

Si vous avez plusieurs exécutions dans un même workflow, vous pouvez également sélectionner le filtre status après avoir choisi votre workflow, et sélectionner la valeur Failure (Échec) pour afficher uniquement les exécutions qui ont échoué dans ce workflow.

Accéder aux journaux de workflow à partir de l’API REST

En plus d’afficher les journaux à l’aide de GitHub, vous pouvez également utiliser l’API REST de GitHub pour afficher les journaux des exécutions de workflows, pour réexécuter des workflows et même pour annuler des exécutions de workflows. Pour afficher le journal d’une exécution de workflow à l’aide de l’API, vous devez envoyer une demande GET au point de terminaison des journaux. N’oubliez pas que quiconque disposant d’un accès en lecture au dépôt peut utiliser ce point de terminaison. Si le dépôt est privé, vous devez utiliser un jeton d’accès avec l’étendue repo.

Par exemple, une demande GET pour afficher un journal d’exécution de workflow spécifique suivrait ce chemin :

GET /repos/{owner}/{repo}/actions/runs/{run_id}/logs