Personnaliser votre flux de travail avec des variables d’environnement

Dans cette unité, vous allez apprendre à configurer et à gérer un comportement spécifique à l’environnement à l’aide de variables, de contextes et de scripts personnalisés dans des flux de travail GitHub Actions.

Pour implémenter ce processus, vous allez apprendre à :

• Utilisez les variables d’environnement par défaut et personnalisées.
• Accéder aux informations contextuelles dans les flux de travail.
• Définissez des variables d’environnement dans différentes étendues de flux de travail.
• Utilisez des scripts personnalisés avec le mot clé d’exécution.
• Appliquez des protections d’environnement pour les déploiements.

Contextes et variables d’environnement par défaut

Dans le workflow GitHub Actions, plusieurs variables d’environnement par défaut sont disponibles pour vous permettre d’utiliser, mais uniquement dans l’exécuteur qui exécute un 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 un accès aux informations d’environnement. Ils présentent toutefois des différences importantes. Bien que les variables d’environnement par défaut ne puissent être utilisées que dans l’exécuteur, vous pouvez utiliser des variables de contexte à tout moment dans le flux de travail. 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. Si la branche est main, l’exécuteur est exécuté et imprime « Déploiement sur le serveur de production sur la branche $GITHUB_REF ». La variable $GITHUB_REF d’environnement par défaut est utilisée dans l’exécuteur pour faire référence à la branche. Notez que les variables d’environnement par défaut sont toutes en majuscules, alors que les variables de contexte sont en minuscules.

Informations contextuelles disponibles dans un flux de travail

Utilisez des contextes pour accéder aux informations sur les exécutions de flux de travail, les variables, les environnements d’exécuteur, les travaux et les étapes. Chaque contexte est un objet qui contient des propriétés qui peuvent être d’autres objets ou chaînes. Les contextes disponibles incluent github, env, vars, job, jobs, steps, runner, secrets, strategy, matrix, needs, et inputs.

Le tableau suivant répertorie les contextes et descriptions de flux de travail :

Différents contextes sont disponibles à différents moments dans une exécution de flux de travail. Par exemple, vous pouvez utiliser le contexte secrets uniquement à des endroits spécifiques d’une tâche. En outre, vous pouvez utiliser certaines fonctions, comme la hashFiles fonction, uniquement dans des endroits spécifiques.

Le tableau suivant répertorie les restrictions pour chaque contexte et fonction spéciale dans un flux de travail. Les contextes répertoriés sont disponibles uniquement pour la clé de flux de travail indiquée. Vous ne pouvez pas les utiliser ailleurs. Vous pouvez utiliser une fonction n’importe où, sauf si elle est répertoriée dans le tableau suivant.

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

Définir des variables d’environnement personnalisées dans un flux de travail

Vous pouvez définir des variables d’environnement qui sont étendues à l’ensemble du flux de travail à l’aide env du niveau supérieur du fichier de flux de travail. Définissez la portée du contenu d’un travail au sein d’un flux de travail à l’aide de jobs.<job_id>.env. Vous pouvez définir une variable d'environnement à une étape spécifique au sein d'un travail en utilisant jobs.<job_id>.steps[*].env.

Voici un exemple montrant les trois scénarios d’un fichier de flux de travail :

name: Greeting on variable day

on:
  workflow_dispatch

env:
  DAY_OF_WEEK: Monday

jobs:
  greeting_job:
    runs-on: ubuntu-latest
    env:
      Greeting: Hello
    steps:
      - name: "Say Hello Mona it's Monday"
        run: echo "$Greeting $First_Name. Today is $DAY_OF_WEEK!"
        env:
          First_Name: Mona

Utiliser un contexte par défaut dans un flux de travail

La plateforme GitHub définit les variables d’environnement par défaut. Ils ne sont pas définis dans un flux de travail, mais vous pouvez utiliser une variable d’environnement par défaut dans un flux de travail dans le contexte approprié. La plupart de ces variables, autres que CI, commencent par GITHUB_* ou RUNNER_*. Les deux derniers types ne peuvent pas être remplacés. En outre, ces variables par défaut ont une propriété de contexte correspondante et nommée de la même façon. Par exemple, la RUNNER_* série de variables par défaut a une propriété de contexte correspondante de runner.*.

Voici un exemple d’accès aux variables par défaut dans un flux de travail en appliquant ces méthodes :

on: workflow_dispatch

jobs:
  if-Windows-else:
    runs-on: macos-latest
    steps:
      - name: condition 1
        if: runner.os == 'Windows'
        run: echo "The operating system on the runner is $env:RUNNER_OS."
      - name: condition 2
        if: runner.os != 'Windows'
        run: echo "The operating system on the runner is not Windows, it's $RUNNER_OS."

Pour plus d’informations, consultez Variables d’environnement par défaut.

Passer des variables d’environnement personnalisées à un flux de travail

Vous pouvez passer des variables d’environnement personnalisées d’une étape d’un travail de flux de travail aux étapes suivantes dans le travail. Générez une valeur dans une étape d’un travail et affectez-la à une variable d’environnement existante ou nouvelle. Ensuite, vous écrivez la paire variable/valeur dans le fichier d’environnement GITHUB_ENV. Vous pouvez utiliser le fichier d’environnement dans une action ou à partir d’une commande shell dans la tâche de flux de travail à l’aide du run mot clé.

L’étape qui crée ou met à jour la variable d’environnement n’a pas accès à la nouvelle valeur, mais toutes les étapes suivantes d’un travail ont accès.

Voici un exemple :

steps:
  - name: Set the value
    id: step_one
    run: |
      echo "action_state=yellow" >> "$GITHUB_ENV"
  - name: Use the value
    id: step_two
    run: |
      printf '%s\n' "$action_state" # This will output 'yellow'

Ajouter des protections d’environnement

Vous pouvez ajouter des règles de protection pour les environnements définis pour votre dépôt GitHub.

Pour ajouter un environnement, dans votre référentiel :

1. Sélectionnez Paramètres.

   

2. Dans le volet gauche, sélectionnez Environnement.

   

3. Sélectionnez le bouton Nouvel environnement pour ajouter et configurer un environnement et ajouter des protections.

   

À propos des environnements

Utilisez des environnements pour décrire une cible de déploiement générale comme la production, la préproduction ou le développement. Lorsqu’un flux de travail GitHub Actions est déployé dans un environnement, l’environnement apparaît sur la page principale du référentiel. Vous pouvez utiliser des environnements pour exiger l’approbation d’un travail, restreindre les branches qui peuvent déclencher un flux de travail, gérer les déploiements à l’aide de règles de protection de déploiement personnalisées ou limiter l’accès aux secrets.

Chaque travail d’un workflow peut référencer un environnement. Toutes les règles de protection que vous définissez pour l’environnement doivent réussir avant qu’une tâche qui référence l’environnement soit envoyée à un exécuteur. La tâche peut accéder aux secrets de l’environnement seulement après que la tâche ait été envoyée à un exécuteur.

Lorsqu’un flux de travail fait référence à un environnement, l’environnement apparaît dans les déploiements du référentiel.

Règles de protection d’environnement

Les règles de protection du déploiement d’environnement exigent que des conditions spécifiques soient remplies avant qu'un travail référant à cet environnement ne puisse continuer. Vous pouvez utiliser des règles de protection de déploiement pour exiger une approbation manuelle, retarder un travail ou restreindre l’environnement à des branches spécifiques. Vous pouvez également créer et implémenter des règles de protection personnalisées optimisées par GitHub Apps pour utiliser des systèmes partenaires pour contrôler les déploiements qui référencent les environnements configurés sur GitHub.

Voici une explication de ces règles de protection :

• Règles de protection requises pour les réviseurs. Utilisez cette règle pour exiger qu’une personne ou une équipe spécifique approuve les travaux de flux de travail qui référencent l’environnement. Vous pouvez lister jusqu’à six utilisateurs ou équipes comme réviseurs. Les réviseurs doivent disposer d’au moins des autorisations de lecture sur le référentiel. Un seul réviseur requis doit approuver le travail pour qu’il continue.

  Vous pouvez également empêcher l’auto-révision des déploiements dans un environnement protégé. Si vous activez ce paramètre, les utilisateurs qui lancent un déploiement ne peuvent pas approuver le travail de déploiement, même s’ils sont un réviseur requis. En activant les auto-révisions, il garantit que plusieurs personnes passent en revue les déploiements dans des environnements protégés.

  Pour plus d'informations sur l'examen des tâches référant à un environnement avec réviseurs requis, voir Examiner les déploiements.

• Règles de projection du minuteur d’attente. Vous pouvez utiliser une règle de protection via un minuteur d’attente pour retarder un processus pendant une durée déterminée après son déclenchement initial et avant que le déploiement de l’environnement ne continue. Le temps (en minutes) doit être un entier compris entre 1 et 43 200 (30 jours). Le temps d’attente ne compte pas vers votre temps facturable.

• Règles de protection des branches et balises. Vous pouvez utiliser les règles de protection pour les branches et balises de déploiement afin de limiter les branches et balises utilisées pour le déploiement dans l’environnement. Vous avez plusieurs options concernant les règles de protection des branches et des balises d’un environnement.

  • Aucune restriction ne s’applique quant à la branche ou la balise qui peut être déployée dans l’environnement.
  • Les branches protégées autorisent uniquement les branches ayant des règles de protection de branche activées pour le déploiement dans l’environnement. Si aucune règle de protection de branche n’est définie pour une branche dans le référentiel, toutes les branches peuvent se déployer. Le paramètre Branches et balises sélectionnées garantit que seules les branches et les balises qui correspondent à vos modèles de nom spécifiés peuvent être déployées dans l’environnement.
  • Si vous spécifiez releases/* comme une branche de déploiement ou une règle de balise, seule une branche ou une balise portant un nom commençant par releases/ peut être déployée dans l’environnement. (Les caractères génériques ne correspondent pas à /. Pour faire correspondre des branches ou des balises qui commencent par release/ et contiennent une autre barre oblique unique, utilisez release/*/*.) Si vous ajoutez main comme une règle de branche, une branche nommée main peut aussi être déployée dans l’environnement.

• Règles de protection de déploiement personnalisées. Vous pouvez créer des règles de protection personnalisées pour gérer l’accès des déploiements à l’utilisation des services partenaires. Par exemple, vous pouvez utiliser des systèmes d’observabilité, des systèmes de gestion des modifications, des systèmes de qualité du code ou d’autres configurations manuelles que vous utilisez pour évaluer la préparation et fournir des approbations automatisées pour les déploiements sur GitHub.

  Après avoir créé des règles de protection de déploiement personnalisées et les installer sur un référentiel, vous pouvez activer la règle de protection de déploiement personnalisée pour n’importe quel environnement du référentiel.

  

Scripts de votre workflow

Dans les exemples d’extraits de workflows précédents, le mot clé run est utilisé pour afficher une chaîne de texte. Étant donné que le mot clé run indique à la tâche 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 bats package de test logiciel à l’aide du run mot clé. 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