Le système de variables de GitLab CI vous permet d’injecter des données dans vos environnements de travail CI. Vous pouvez utiliser des variables pour fournir des valeurs de configuration, créer des pipelines réutilisables et éviter de coder en dur des informations sensibles dans vos fichiers .gitlab-ci.yml.
Dans ce guide, nous allons voir comment vous pouvez définir et utiliser des variables dans votre propre système de CI. Plusieurs options sont disponibles en fonction de l’endroit où vous souhaitez que les valeurs soient affichées et de la fréquence à laquelle vous souhaitez les modifier.
Les bases
Dans leur forme la plus simple, les variables sont des paires clé-valeur qui sont injectées comme variables d’environnement dans le contexte d’exécution de votre pipeline. Vous pouvez les référencer dans votre fichier .gitlab-ci.yml comme des variables d’environnement standard :
test :
script :
– echo « $EXAMPLE_VARIABLE ».
Vous pouvez échapper au caractère $ en utilisant la syntaxe $$VARIABLE :
test :
script :
– echo « $$EXAMPLE_VARIABLE »
Dans cet exemple, $EXAMPLE_VARIABLE sera enregistré, au lieu de la valeur de la variable EXAMPLE_VARIABLE comme indiqué ci-dessus.
Les variables sont disponibles dans l’environnement du travail. Elles peuvent également être interpolées dans les valeurs d’autres champs de votre fichier .gitlab-ci.yml, permettant une configuration dynamique du pipeline :
build :
image : $CI_REGISTRY_IMAGE/build-utils:latest
GitLab CI définit plusieurs variables intégrées qui sont toujours disponibles. Celles-ci incluent les détails du commit, de la branche et de la demande de fusion sur lesquels le pipeline s’exécute. Les variables prédéfinies permettent également d’accéder aux informations d’identification par tâche pour accéder à d’autres fonctionnalités de GitLab telles que le registre des conteneurs et le proxy de dépendances.
Au-delà de ces variables intégrées, vous pouvez définir vos propres valeurs à plusieurs endroits. Les variables sont prises en charge au niveau de l’instance, du groupe, du projet et du pipeline, ce qui vous donne une certaine souplesse pour définir des valeurs de repli, des valeurs par défaut et des dérogations. Vous pouvez définir des variables à l’aide de l’interface utilisateur de GitLab ou de l’API ; nous nous concentrerons sur l’interface utilisateur dans ce guide.
Définition d’une variable
Les variables sont créées dans l’écran Paramètres > CI/CD > Variables de la portée dans laquelle vous souhaitez qu’elles soient disponibles. Pour une variable de niveau projet, cela signifie qu’il faut aller dans Paramètres > CI/CD depuis la barre latérale gauche de GitLab tout en visualisant une page du projet. De même, pour les variables de niveau groupe, naviguez vers le groupe et utilisez la barre latérale pour atteindre ses paramètres de CI. Les variables de niveau instance sont localisées par le même chemin dans la zone d’administration de GitLab.
Développez la section « Variables » pour afficher toutes les variables qui ont déjà été définies. Cliquez sur le bouton bleu « Add variable » pour commencer à ajouter un nouvel élément à la liste.
Chaque variable doit avoir une clé unique ; c’est ainsi que vous ferez référence à la variable dans votre pipeline et ses scripts. Le nom que vous choisissez doit être compatible avec le shell qui exécutera votre travail. Si vous choisissez un mot clé réservé, votre travail pourrait échouer. Toutes les variables doivent être des chaînes de caractères valides contenant uniquement des caractères alphanumériques et des traits de soulignement.
Définissez ensuite la valeur de votre variable. Si le menu déroulant « Type » est laissé sur « Variable », cette valeur sera injectée telle quelle chaque fois que vous ferez référence à la variable dans votre pipeline. Si vous changez le type en « File », la valeur sera injectée en tant que fichier temporaire dans votre environnement de construction ; la valeur de la variable d’environnement sera le chemin d’accès à ce fichier temporaire. Cela peut être un moyen plus sûr d’injecter des données sensibles si votre application est prête à lire la valeur finale du fichier spécifié.
Une fois que vous avez terminé, cliquez sur le bouton vert « Ajouter une variable » pour terminer le processus. Vous pouvez maintenant faire référence à votre variable dans les pipelines qui s’exécutent dans la portée dans laquelle vous l’avez définie. Pour une variable de projet, elle sera définie pour les pipelines de ce projet, tandis que les variables de niveau instance seront disponibles pour chaque pipeline sur votre serveur GitLab.
Les variables peuvent être gérées à tout moment en retournant à l’écran des paramètres de la portée dans laquelle elles sont définies. Cliquez sur le bouton Modifier (icône en forme de crayon) en regard d’une variable pour afficher la boîte de dialogue d’édition et modifier les propriétés de la variable. Cette boîte de dialogue permet également de supprimer les variables redondantes.
Variables protégées
Les variables peuvent être marquées comme « protégées » en cochant la case dans la boîte de dialogue « Ajouter une variable ». Cette option signifie que la variable ne sera définie que dans les pipelines s’exécutant sur des branches ou des balises protégées.
Les variables protégées sont idéales dans les cas où vous exposez une valeur sensible, comme une clé de déploiement, qui ne sera pas utilisée dans tous les pipelines. En limitant cette valeur aux seuls pipelines qui en ont réellement besoin (comme les tâches de déploiement s’exécutant sur votre branche de publication protégée), vous réduisez le risque de fuite accidentelle.
Variables masquées
L’option « Mask variable » est un autre moyen d’améliorer la sécurité de vos variables. Lorsque cette case à cocher est activée, GitLab filtrera automatiquement la valeur de la variable dans les journaux de travaux collectés. Tout écho non intentionnel $SECRET_VALUE sera nettoyé, réduisant ainsi le risque qu’un utilisateur voie une valeur de jeton sensible lorsqu’il inspecte les journaux de travaux à l’aide de l’interface Web de GitLab.
Pour que le masquage soit efficace, les valeurs variables doivent être détectables de manière fiable dans les journaux. Par conséquent, il ne fonctionne que pour les valeurs qui répondent à des exigences de formatage spécifiques. Les formats de jetons d’authentification les plus courants, ainsi que toutes les données codées en Base64, seront compatibles. Le masquage ne fonctionne que pour les valeurs d’une taille maximale de 4 KiB.
Variables de niveau environnement
Les variables peuvent être affectées à des environnements spécifiques. Cette fonctionnalité permet à vos pipelines de fonctionner avec une configuration différente selon l’environnement dans lequel ils sont déployés.
Utilisez la liste déroulante « Environment scope » dans la boîte de dialogue « Add variable » pour sélectionner un environnement pour votre variable. La variable ne sera définie que dans les pipelines qui font référence à l’environnement sélectionné via le champ environnement du fichier .gitlab-ci.yml.
Définir des variables dans le fichier .gitlab-ci.yml
Les variables peuvent être définies dans votre fichier .gitlab-ci.yml en utilisant un bloc de variables. Les variables listées ici seront créées pour le travail si elles n’existent pas déjà ; sinon, elles remplaceront la valeur définie au niveau du projet ou à un niveau supérieur.
Les variables peuvent être définies au niveau du pipeline avec une section de variables globales. Les tâches individuelles peuvent également avoir leurs propres variables. Les deux approches sont illustrées ci-dessous, où le travail de mise à disposition remplace la valeur d’une variable au niveau du pipeline et définit en plus une variable unique spécifique au travail.
variables :
DEPLOY_URL : exemple.com
deploy_staging :
variables :
DEPLOY_URL : staging.exemple.com
DEPLOY_IS_STAGING_ENV : true
script :
– ./deploy.sh
deploy_production :
script :
– ./deploy.sh
Les variables définies dans les fichiers .gitlab-ci.yml peuvent parfois être utilisées de manière différente de celles définies dans l’interface utilisateur ou l’API GitLab. Vous pouvez utiliser une variable pour éviter de répéter des sections du fichier, même si ces valeurs ne sont pas susceptibles de changer ou d’être remplacées à l’avenir. Ainsi, les sections de variables peuvent être plus proches des variables des langages de programmation que des clés de type configuration que l’on trouve généralement au niveau du projet et à un niveau supérieur.
Remplacement des variables
Le système de variables de GitLab vous offre plusieurs possibilités de remplacer la valeur d’une variable avant qu’elle ne soit fixée pour un pipeline ou un travail. L’ordre de préséance est relativement complexe mais peut être résumé comme suit :
Les variables prédéfinies de GitLab sont toujours définies en premier.
Les variables définies dans .gitlab-ci.yml sont définies ensuite (les variables de travail sont plus spécifiques que les variables de pipeline).
Les variables définies au niveau de l'instance, du groupe et du projet sont superposées.
Les variables du déclencheur de pipeline spécifique remplacent tout ce qui précède.Vous pouvez toujours exécuter un pipeline avec une valeur de variable spécifique en utilisant l’exécution manuelle. Accédez à la page CI/CD > Pipelines de votre projet et cliquez sur le bouton bleu « Run pipeline » en haut à droite.
Utilisez le menu déroulant pour sélectionner la branche ou la balise sur laquelle exécuter le pipeline. Utilisez ensuite le tableau « Variables » pour définir les variables à ajouter à l’exécution du pipeline. Celles-ci deviendront les valeurs les plus spécifiques, appliquées en tant que dernière étape de l’ordre de préséance des variables. Les variables définies ici ne seront pas sauvegardées ou réutilisées dans un pipeline ultérieur.
Résumé
L’implémentation des variables CI de GitLab est un mécanisme puissant et flexible pour configurer vos pipelines. Il y a tellement d’endroits où les variables peuvent être définies qu’il peut être difficile de savoir où une valeur doit être placée.
En général, il est plus efficace de placer autant de valeurs que possible au niveau du groupe afin de ne pas avoir à vous répéter dans vos projets. Vous pouvez toujours remplacer une variable plus tard dans des projets spécifiques qui nécessitent une valeur différente. Les administrateurs de GitLab auto-hébergés peuvent utiliser des variables d’instance pour exposer des valeurs communes partagées, bien que cela puisse entraîner une exposition involontaire d’informations si ce n’est pas soigneusement géré.