Où les variables peuvent être utilisées

{{< details >}}

• Édition : Gratuite, GitLab Premium, GitLab Ultimate
• Offre : GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Comme décrit dans la documentation sur les variables CI/CD, vous pouvez définir de nombreuses variables différentes. Certaines d'entre elles peuvent être utilisées pour toutes les fonctionnalités GitLab CI/CD, mais d'autres sont plus ou moins limitées.

Ce document décrit où et comment les différents types de variables peuvent être utilisés.

Utilisation des variables {#variables-usage}

Il existe deux endroits où les variables définies peuvent être utilisées. Sur le :

1. Côté GitLab, dans le fichier .gitlab-ci.yml.
2. Côté GitLab Runner, dans config.toml.

Fichier .gitlab-ci.yml {#gitlab-ciyml-file}

{{< history >}}

• Prise en charge des variables CI_ENVIRONMENT_* à l'exception de CI_ENVIRONMENT_SLUG introduite dans GitLab 16.4.

{{< /history >}}

- Variables CI_ENVIRONMENT_*.

• Variables persistées. | | environment:url | oui | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab.

Sont prises en charge toutes les variables définies pour un job (variables de projet/groupe, variables provenant de .gitlab-ci.yml, variables provenant de déclencheurs, variables provenant de planifications de pipeline).

Ne sont pas prises en charge les variables définies dans le fichier config.toml de GitLab Runner et les variables créées dans le script du job. | | environment:deployment_tier | oui | GitLab | Similaire à environment:url, mais l'expansion des variables ne prend pas en charge les éléments suivants :

- Variables CI_ENVIRONMENT_*.

• Variables persistées. | | environment:auto_stop_in | oui | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab.

La valeur de la variable substituée doit représenter une période de temps sous une forme en langage naturel lisible. Consultez les valeurs prises en charge pour plus d'informations. | | environment:kubernetes:agent | oui | GitLab | Similaire à environment:url, mais l'expansion des variables ne prend pas en charge les éléments suivants :

- Variables CI_ENVIRONMENT_*.

• Variables persistées. | | environment:kubernetes:namespace | oui | GitLab | Similaire à environment:url, mais l'expansion des variables ne prend pas en charge les éléments suivants :

- Variables CI_ENVIRONMENT_*.

• Variables persistées. | | id_tokens:aud | oui | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab. L'expansion des variables a été introduite dans GitLab 16.1. | | image | oui | Runner | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables de GitLab Runner. | | include | oui | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab.

Consultez Utiliser des variables avec include pour plus d'informations sur les variables prises en charge. | | resource_group | oui | GitLab | Similaire à environment:url, mais l'expansion des variables ne prend pas en charge les éléments suivants :

• CI_ENVIRONMENT_URL
• Variables persistées. | | rules:changes | non | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab. | | rules:changes:compare_to | non | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab. | | rules:exists | non | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab. | | rules:if | non | Non applicable | La variable doit être sous la forme $variable. Les éléments suivants ne sont pas pris en charge :

- La variable CI_ENVIRONMENT_SLUG.

• Variables persistées. | | script | oui | Shell d'exécution de script | L'expansion des variables est effectuée par l'environnement shell d'exécution. | | services:name | oui | Runner | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables de GitLab Runner. | | tags | oui | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab. | | trigger et trigger:project | oui | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab. L'expansion des variables pour trigger:project a été introduite dans GitLab 15.3. | | variables | oui | GitLab/Runner | L'expansion des variables est d'abord effectuée par le mécanisme interne d'expansion des variables dans GitLab, puis toutes les variables non reconnues ou indisponibles sont étendues par le mécanisme interne d'expansion des variables de GitLab Runner. | | workflow:name | oui | GitLab | L'expansion des variables est effectuée par le mécanisme interne d'expansion des variables dans GitLab.

Sont prises en charge toutes les variables disponibles dans workflow : - Variables de projet/groupe.

• variables global et workflow:rules:variables (lorsque la règle est satisfaite). - Variables héritées des pipelines parents. - Variables provenant de déclencheurs. - Variables provenant de planifications de pipeline.

Ne sont pas prises en charge les variables définies dans le fichier config.toml de GitLab Runner, les variables définies dans les jobs, ni les variables persistées. |

Fichier config.toml {#configtoml-file}

Vous pouvez en savoir plus sur config.toml dans la documentation de GitLab Runner.

Mécanismes d'expansion {#expansion-mechanisms}

Il existe trois mécanismes d'expansion :

• GitLab
• GitLab Runner
• Environnement shell d'exécution

Mécanisme interne d'expansion des variables GitLab {#gitlab-internal-variable-expansion-mechanism}

La partie à étendre doit être sous la forme $variable, ${variable} ou %variable%. Chaque forme est traitée de la même manière, quel que soit le système d'exploitation ou le shell qui gère le job, car l'expansion est effectuée dans GitLab avant que tout runner ne reçoive le job.

Expansion des variables imbriquées {#nested-variable-expansion}

GitLab développe les valeurs des variables de job de manière récursive avant de les envoyer au runner. Par exemple, dans le scénario suivant :

- BUILD_ROOT_DIR: '${CI_BUILDS_DIR}'
- OUT_PATH: '${BUILD_ROOT_DIR}/out'
- PACKAGE_PATH: '${OUT_PATH}/pkg'

Le runner reçoit un chemin valide et complet. Par exemple, si ${CI_BUILDS_DIR} est /output, alors PACKAGE_PATH serait /output/out/pkg.

Les références aux variables indisponibles sont conservées telles quelles. Dans ce cas, le runner tente d'étendre la valeur de la variable à l'exécution. Par exemple, une variable comme CI_BUILDS_DIR n'est connue du runner qu'à l'exécution.

Mécanisme interne d'expansion des variables de GitLab Runner {#gitlab-runner-internal-variable-expansion-mechanism}

• Pris en charge : variables de projet/groupe, variables .gitlab-ci.yml, variables config.toml, et variables provenant de déclencheurs, de planifications de pipeline et de pipelines manuels.
• Non pris en charge : variables définies à l'intérieur des scripts (par exemple, export MY_VARIABLE="test").

Le runner utilise la méthode os.Expand() de Go pour l'expansion des variables. Cela signifie qu'il ne traite que les variables définies sous la forme $variable et ${variable}. Il est également important de noter que l'expansion n'est effectuée qu'une seule fois, de sorte que les variables imbriquées peuvent fonctionner ou non, selon l'ordre des définitions de variables et selon que l'expansion des variables imbriquées est activée dans GitLab.

Pour les téléversements d'artefacts et de cache, le runner utilise mvdan.cc/sh/v3/expand pour l'expansion des variables à la place de os.Expand() de Go, car mvdan.cc/sh/v3/expand prend en charge l'expansion des paramètres.

Environnement shell d'exécution {#execution-shell-environment}

Il s'agit d'une phase d'expansion qui se produit lors de l'exécution de script. Son comportement dépend du shell utilisé (bash, sh, cmd, PowerShell). Par exemple, si le script du job contient une ligne echo $MY_VARIABLE-${MY_VARIABLE_2}, elle devrait être correctement traitée par bash/sh (laissant des chaînes vides ou certaines valeurs selon que les variables sont définies ou non), mais ne fonctionne pas avec cmd ou PowerShell de Windows, car ces shells utilisent une syntaxe de variables différente.

Pris en charge :

• Le script peut utiliser toutes les variables disponibles par défaut pour le shell (par exemple, $PATH qui devrait être présent dans tous les shells bash/sh) et toutes les variables définies par GitLab CI/CD (variables de projet/groupe, variables .gitlab-ci.yml, variables config.toml, et variables provenant de déclencheurs et de planifications de pipeline).
• Le script peut également utiliser toutes les variables définies dans les lignes précédentes. Ainsi, par exemple, si vous définissez une variable export MY_VARIABLE="test" :
  • Dans before_script, cela fonctionne dans les lignes suivantes de before_script et dans toutes les lignes du script associé.
  • Dans script, cela fonctionne dans les lignes suivantes de script.
  • Dans after_script, cela fonctionne dans les lignes suivantes de after_script.

Dans le cas des scripts after_script, ils peuvent :

• Utiliser uniquement les variables définies avant le script dans la même section after_script.
• Ne pas utiliser les variables définies dans before_script et script.

Ces restrictions existent parce que les scripts after_script sont exécutés dans un contexte shell séparé.

Variables persistées {#persisted-variables}

Certaines variables prédéfinies sont dites persistées. Les variables persistées sont :

• Prises en charge pour les définitions dont le lieu d'expansion est :
  • Runner.
  • Shell d'exécution de script.
• Non prises en charge :
  • Pour les définitions dont le lieu d'expansion est GitLab.
  • Dans les expressions de variables rules.

Les jobs de déclenchement de pipeline ne peuvent pas utiliser les variables persistées au niveau du job, mais peuvent utiliser les variables persistées au niveau du pipeline.

Certaines variables persistées contiennent des jetons et ne peuvent pas être utilisées dans certaines définitions pour des raisons de sécurité.

Variables persistées au niveau du pipeline :

• CI_PIPELINE_ID
• CI_PIPELINE_URL

Variables persistées au niveau du job :

• CI_DEPLOY_PASSWORD
• CI_DEPLOY_USER
• CI_JOB_ID
• CI_JOB_STARTED_AT
• CI_JOB_TOKEN
• CI_JOB_URL
• CI_PIPELINE_CREATED_AT
• CI_REGISTRY_PASSWORD
• CI_REGISTRY_USER
• CI_REPOSITORY_URL

Variables avec une portée d'environnement {#variables-with-an-environment-scope}

Les variables définies avec une portée d'environnement sont prises en charge. Étant donné qu'une variable $STAGING_SECRET est définie dans une portée de review/staging/*, le job suivant utilisant des environnements dynamiques est créé, sur la base de l'expression de variable correspondante :

my-job:
  stage: staging
  environment:
    name: review/$CI_JOB_STAGE/deploy
  script:
    - 'deploy staging'
  rules:
    - if: $STAGING_SECRET == 'something'