Transmettre des variables dotenv à des jobs spécifiques

{{< details >}}

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

{{< /details >}}

Pour transmettre des variables d'environnement à d'autres jobs, utilisez un fichier dotenv. Un fichier dotenv est un fichier avec l'extension .env qui stocke une liste de clés et de valeurs de variables d'environnement. Par exemple, dans un fichier sample.env :

REVIEW_URL=review.example.com/123456
BUILD_VERSION=v1.0.0

Enregistrez le fichier dotenv en tant qu'artefact de rapport dotenv, qui peut être transmis à d'autres jobs dans le même pipeline, aux pipelines downstream, ou pour définir des URL d'environnement dynamiques.

Vous pouvez utiliser les variables dotenv des façons suivantes :

• Générer des valeurs dans un job et les utiliser dans les jobs suivants.
• Transmettre des valeurs calculées entre les étapes du pipeline.
• Définir des URL d'environnement dynamiques en fonction des sorties de déploiement.
• Partager des variables entre des pipelines multi-projets.

Vous pouvez utiliser des variables dotenv dans les sections script des jobs ou avec des mots-clés qui prennent en charge l'expansion des variables sur le runner. Vous ne pouvez pas utiliser de variables dotenv dans les sections rules.

Les variables dotenv ont la priorité sur les variables de job et les variables par défaut définies dans .gitlab-ci.yml, mais pas sur les variables de projet, de groupe, d'instance ou de pipeline.

Si le même nom de variable apparaît plusieurs fois dans un rapport dotenv, la dernière valeur est utilisée.

Transmettre des variables à des jobs ultérieurs {#pass-variables-to-later-jobs}

Par défaut, les variables dotenv sont disponibles pour tous les jobs dans les étapes ultérieures. Pour transmettre des variables entre des jobs :

1. Dans un job, créez un fichier (par exemple, build.env) avec des variables au format VARIABLE_NAME=value, une variable par ligne.
2. Exportez le fichier en tant qu'artefact de rapport dotenv.
3. Dans les jobs ultérieurs, utilisez les variables dans vos scripts.

Par exemple, build-job crée build.env avec BUILD_VERSION=v1.0.0, et test-job le reçoit automatiquement comme variable d'environnement :

build-job:
  stage: build
  script:
    - echo "BUILD_VERSION=v1.0.0" >> build.env
  artifacts:
    reports:
      dotenv: build.env

test-job:
  stage: test
  script:
    - echo "Testing version $BUILD_VERSION"  # Output: 'Testing version v1.0.0'

[!warning] N'incluez pas de données sensibles telles que des identifiants, des clés API ou des jetons dans les fichiers dotenv. Les utilisateurs du pipeline peuvent accéder au contenu des fichiers dotenv. Pour restreindre l'accès, utilisez artifacts:access.

Contrôler quels jobs reçoivent les variables dotenv {#control-which-jobs-receive-dotenv-variables}

Pour contrôler quels jobs reçoivent les variables dotenv, utilisez les mots-clés dependencies ou needs.

Hériter de jobs spécifiques {#inherit-from-specific-jobs}

Utilisez dependencies pour limiter l'héritage à des jobs spécifiques uniquement :

build-job1:
  stage: build
  script:
    - echo "BUILD_VERSION=v1.0.0" >> build.env
  artifacts:
    reports:
      dotenv: build.env

build-job2:
  stage: build
  script:
    - echo "This job has no dotenv artifacts"

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: 'v1.0.0'
  dependencies:
    - build-job1
    # build-job2 is not listed, so its artifacts are not inherited

Exclure des variables dotenv {#exclude-dotenv-variables}

Pour empêcher un job de recevoir des variables dotenv d'un job nommé, utilisez needs avec artifacts: false. Cela bloque tous les téléchargements d'artefacts de ce job, pas seulement les variables dotenv :

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: '' (empty)
  needs:
    - job: build-job1
      artifacts: false

Le needs dans cet exemple fait également démarrer le job dès que build-job1 est terminé.

Ou utilisez un tableau dependencies vide pour bloquer les téléchargements d'artefacts de tous les jobs en amont :

test-job:
  stage: test
  script:
    - echo "$BUILD_VERSION"  # Output: '' (empty)
  dependencies: []

Transmettre des variables aux pipelines downstream {#pass-variables-to-downstream-pipelines}

Vous pouvez transmettre des variables dotenv à un pipeline downstream grâce à l'héritage des variables dotenv. Dans un pipeline multi-projets, créez l'artefact dotenv dans un job en amont et utilisez needs dans le job downstream pour en hériter :

1. Enregistrez les variables dans un fichier .env.
2. Enregistrez le fichier .env en tant qu'artefact de rapport dotenv.
3. Déclenchez le pipeline downstream.

build_vars:
  stage: build
  script:
    - echo "BUILD_VERSION=hello" >> build.env
  artifacts:
    reports:
      dotenv: build.env

deploy:
  stage: deploy
  trigger: my/downstream_project

Dans le pipeline downstream, configurez le job pour hériter des artefacts du job en amont avec needs. Le job reçoit les variables dotenv et peut ensuite accéder à BUILD_VERSION dans le script :

test:
  stage: test
  script:
    - echo $BUILD_VERSION
  needs:
    - project: my/upstream_project
      job: build_vars
      ref: master
      artifacts: true

Définir une URL d'environnement dynamique {#set-a-dynamic-environment-url}

Vous pouvez utiliser des variables dotenv pour définir une URL d'environnement dynamique après la fin d'un job de déploiement. Cela est utile lorsqu'une plateforme d'hébergement externe génère une URL dynamiquement pour chaque déploiement.

Pour plus d'informations, consultez Définir une URL d'environnement dynamique.

Stocker des valeurs complexes {#store-complex-values}

Les fichiers dotenv présentent des limitations de format spécifiques, telles que des restrictions sur les valeurs multilignes et les caractères spéciaux nécessitant un échappement. Si votre valeur contient du JSON, s'étend sur plusieurs lignes ou inclut des caractères nécessitant un échappement, évitez d'utiliser des variables dotenv. Utilisez plutôt un artefact de fichier distinct. Pour la liste complète des contraintes de valeur, consultez les exigences de format.

Au lieu de :

# Not supported
- echo 'CONFIG={"key": "value"}' >> build.env

Utilisez un artefact distinct :

build-job:
  stage: build
  script:
    - echo '{"key": "value"}' > config.json
  artifacts:
    paths:
      - config.json

Exigences relatives aux fichiers dotenv {#dotenv-file-requirements}

Les fichiers dotenv doivent satisfaire les exigences suivantes en matière de format, de taille et de variables.

GitLab utilise le gem dotenv pour gérer les fichiers dotenv, mais applique des restrictions supplémentaires au-delà des règles dotenv d'origine et de l'implémentation du gem.

Exigences de format {#format-requirements}

• Seul l'encodage UTF-8 est pris en charge.
• Le fichier ne peut pas contenir de lignes vides ni de commentaires (lignes commençant par #).
• Les noms de variables peuvent uniquement contenir des lettres ASCII (A-Za-z), des chiffres (0-9) et des tirets bas (_).
• Le fichier dotenv ne prend pas en charge les guillemets. Les guillemets simples ou doubles sont conservés tels quels et ne peuvent pas être utilisés pour l'échappement.
• Les valeurs ne peuvent pas contenir de sauts de ligne ou d'autres caractères spéciaux nécessitant un échappement.
• Les valeurs multilignes ne sont pas prises en charge. GitLab rejette le fichier lors du chargement.
• Les espaces et les caractères de saut de ligne (\n) en début et en fin de valeur sont supprimés.

Limites de taille et de variables {#size-and-variable-limits}

Pour les limites d'édition de GitLab.com, consultez les paramètres CI/CD de GitLab.com.

Pour modifier ces limites sur GitLab Self-Managed, consultez les limites CI/CD.