Variables de mise en production et d’artefacts classiques

  • Article

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Les variables de mise en production et d’artefacts classiques constituent un moyen pratique d’échanger et de transporter des données dans votre pipeline. Chaque variable est stockée en tant que chaîne et sa valeur peut changer entre les exécutions de votre pipeline.

Les variables se distinguent des paramètres d’exécution qui sont disponibles uniquement au moment de l’analyse des modèles.

Quand vous composez les tâches de déploiement de votre application dans chaque phase de vos processus CI/CD DevOps, les variables permettent les tâches suivantes :

  • Définir une fois un pipeline de déploiement générique, puis le personnaliser facilement pour chaque phase. Une variable peut par exemple représenter la chaîne de connexion pour le déploiement web. La valeur de cette variable peut varier d’une phase à l’autre. Il s’agit de variables personnalisées.

  • Utiliser des informations sur le contexte de la mise en production, de la phase, des artefacts ou de l’agent particulier dans lequel le pipeline de déploiement est exécuté. Votre script peut par exemple avoir besoin de l’accès à l’emplacement de la build pour la télécharger, ou au répertoire de travail sur l’agent pour créer des fichiers temporaires. Il s’agit de variables par défaut.

Notes

Pour les pipelines YAML, consultez Variables définies par l’utilisateur et Variables prédéfinies pour plus d’informations.

Les variables par défaut

Des informations sur le contexte d’exécution sont mises à la disposition des tâches en cours d’exécution via les variables par défaut. Vos tâches et scripts peuvent utiliser ces variables pour trouver des informations sur le système, la mise en production, la phase ou l’agent dans lequel ils s’exécutent. À l’exception de System.Debug, ces variables sont en lecture seule et leurs valeurs sont définies automatiquement par le système. Certaines des principales variables sont décrites dans les tableaux ci-dessous. Pour afficher la liste complète, consultez Afficher les valeurs actuelles de toutes les variables.

Conseil

Vous pouvez afficher les valeurs actuelles de toutes les variables d’une mise en production et utiliser une variable par défaut pour exécuter une mise en production en mode débogage.

Système

Nom de la variable Description
System.TeamFoundationServerUri URL de la connexion de service dans Azure Pipelines. Utilisez-la à partir de vos scripts ou tâches pour appeler les API REST Azure Pipelines.

Exemple : https://fabrikam.vsrm.visualstudio.com/
System.TeamFoundationCollectionUri URL de la collection Team Foundation ou d’Azure Pipelines. Utilisez-la à partir de vos scripts ou tâches pour appeler les API REST sur d’autres services comme Build et Gestion de version.

Exemple : https://dev.azure.com/fabrikam/
System.CollectionId ID de la collection de cette build ou cette mise en production.

Exemple : 6c6f3423-1c84-4625-995a-f7f143a1e43d
System.DefinitionId ID du pipeline de mise en production de la mise en production actuelle.

Exemple : 1
System.TeamProject Nom du projet de cette build ou cette mise en production.

Exemple : Fabrikam
System.TeamProjectId ID du projet de cette build ou cette mise en production.

Exemple : 79f5c12e-3337-4151-be41-a268d2c73344
System.ArtifactsDirectory Répertoire dans lequel les artefacts sont téléchargés lors du déploiement d’une mise en production. Le répertoire est effacé avant chaque déploiement s’il nécessite le téléchargement d’artefacts sur l’agent. Identique à Agent.ReleaseDirectory et System.DefaultWorkingDirectory.

Exemple : C:\agent\_work\r1\a
System.DefaultWorkingDirectory Répertoire dans lequel les artefacts sont téléchargés lors du déploiement d’une mise en production. Le répertoire est effacé avant chaque déploiement s’il nécessite le téléchargement d’artefacts sur l’agent. Identique à Agent.ReleaseDirectory et System.ArtifactsDirectory.

Exemple : C:\agent\_work\r1\a
System.WorkFolder Répertoire de travail de cet agent, où des sous-dossiers sont créés pour chaque build ou mise en production. Identique à Agent.RootDirectory et Agent.WorkFolder.

Exemple : C:\agent\_work
System.Debug Il s’agit de la seule variable système pouvant être définie par les utilisateurs. Définissez cette valeur sur true pour exécuter la mise en production en mode débogage à des fins de recherche des erreurs.

Exemple : true

Libérer

Nom de la variable Description
Release.AttemptNumber Nombre de fois où cette mise en production est déployée dans cette phase.

Exemple : 1
Release.DefinitionEnvironmentId ID de la phase dans le pipeline de mise en production correspondant.

Exemple : 1
Release.DefinitionId ID du pipeline de mise en production de la mise en production actuelle.

Exemple : 1
Release.DefinitionName Nom du pipeline de mise en production de la mise en production actuelle.

Exemple : fabrikam-cd
Release.Deployment.RequestedFor Nom d’affichage de l’identité qui a déclenché (démarré) le déploiement en cours.

Exemple : Mateo Escobedo
Release.Deployment.RequestedForEmail Adresse e-mail de l’identité qui a déclenché (démarré) le déploiement en cours.

Exemple : mateo@fabrikam.com
Release.Deployment.RequestedForId ID de l’identité qui a déclenché (démarré) le déploiement en cours.

Exemple : 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.DeploymentID ID du déploiement. Unique par travail.

Exemple : 254
Release.DeployPhaseID ID de la phase où le déploiement est en cours d’exécution.

Exemple : 127
Release.EnvironmentId L’ID de l’instance de phase dans une mise en production dans laquelle le déploiement est en cours.

Exemple : 276
Release.EnvironmentName Nom de la phase du déploiement en cours.

Exemple : Dev
Release.EnvironmentUri URI de l’instance de phase dans une mise en production dans laquelle le déploiement est en cours.

Exemple : vstfs://ReleaseManagement/Environment/276
Release.Environments.{stage-name}.status État du déploiement de la phase.

Exemple : InProgress
Release.PrimaryArtifactSourceAlias Alias de la source d’artefact principal

Exemple : fabrikam\_web
Release.Reason Motif du déploiement. Les valeurs prises en charge sont les suivantes :
ContinuousIntegration : la mise en production a démarré dans le déploiement continu une fois la build terminée.
Manual : la mise en production a été démarrée manuellement.
None : le motif du déploiement n’est pas spécifié.
Schedule : la mise en production a démarré à partir d’une planification.
Release.ReleaseDescription Description textuelle fournie au moment de la mise en production.

Exemple : Critical security patch
Release.ReleaseId Identificateur de l’enregistrement de mise en production actuel.

Exemple : 118
Release.ReleaseName Nom de la mise en production actuelle.

Exemple : Release-47
Release.ReleaseUri URI de la mise en production actuelle.

Exemple : vstfs://ReleaseManagement/Release/118
Release.ReleaseWebURL URL de cette mise en production.

Exemple : https://dev.azure.com/fabrikam/f3325c6c/_release?releaseId=392&_a=release-summary
Release.RequestedFor Nom d’affichage de l’identité qui a déclenché la mise en production.

Exemple : Mateo Escobedo
Release.RequestedForEmail Adresse e-mail de l’identité qui a déclenché la mise en production.

Exemple : mateo@fabrikam.com
Release.RequestedForId ID de l’identité qui a déclenché la mise en production.

Exemple : 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.SkipArtifactsDownload Valeur booléenne qui indique si le téléchargement des artefacts sur l’agent doit être ignoré ou non.

Exemple : FALSE
Release.TriggeringArtifact.Alias Alias de l’artefact qui a déclenché la mise en production. Il est vide quand la mise en production a été planifiée ou déclenchée manuellement.

Exemple : fabrikam\_app

Phase de mise en production

Nom de la variable Description
Release.Environments.{stage name}.Status État de déploiement de cette mise en production dans une phase spécifiée.

Exemple : NotStarted

Agent

Nom de la variable Description
Agent.Name Nom de l’agent inscrit auprès du pool d’agents. Il peut être différent du nom de l’ordinateur.

Exemple : fabrikam-agent
Agent.MachineName Nom de l’ordinateur sur lequel l’agent est configuré.

Exemple : fabrikam-agent
Agent.Version Version du logiciel de l’agent.

Exemple : 2.109.1
Agent.JobName Nom du travail en cours d’exécution, comme Release ou Build.

Exemple : Release
Agent.HomeDirectory Dossier dans lequel l’agent est installé. Ce dossier contient le code et les ressources de l’agent.

Exemple : C:\agent
Agent.ReleaseDirectory Répertoire dans lequel les artefacts sont téléchargés lors du déploiement d’une mise en production. Le répertoire est effacé avant chaque déploiement s’il nécessite le téléchargement d’artefacts sur l’agent. Identique à System.ArtifactsDirectory et System.DefaultWorkingDirectory.

Exemple : C:\agent\_work\r1\a
Agent.RootDirectory Répertoire de travail de cet agent, où des sous-dossiers sont créés pour chaque build ou mise en production. Identique à Agent.WorkFolder et System.WorkFolder.

Exemple : C:\agent\_work
Agent.WorkFolder Répertoire de travail de cet agent, où des sous-dossiers sont créés pour chaque build ou mise en production. Identique à Agent.RootDirectory et System.WorkFolder.

Exemple : C:\agent\_work
Agent.DeploymentGroupId ID du groupe de déploiement avec lequel l’agent est inscrit. Disponible uniquement dans les travaux de groupe de déploiement.

Exemple : 1

Artefact général

Pour chaque artefact référencé dans une mise en production, vous pouvez utiliser les variables d’artefact suivantes. Certaines variables ne sont pas significatives dans tous les types d’artefact. Le tableau ci-dessous répertorie les variables d’artefact par défaut et fournit des exemples de valeurs en fonction du type d’artefact. Un exemple vide signifie que la variable n’est pas remplie pour ce type d’artefact.

Remplacez l’espace réservé {alias} par la valeur que vous avez spécifiée pour l’alias d’artefact ou par la valeur par défaut générée pour le pipeline de mise en production.

Nom de la variable Description
Release.Artifacts.{alias}.DefinitionId Identificateur du pipeline ou du référentiel de build.

Exemple pour Azure Pipelines : 1
Exemple pour GitHub : fabrikam/asp
Release.Artifacts.{alias}.DefinitionName Nom du pipeline ou du référentiel de build.

Exemple pour Azure Pipelines : fabrikam-ci
Exemple pour TFVC : $/fabrikam
Exemple pour Git : fabrikam
Exemple pour GitHub : fabrikam/asp (main)
Release.Artifacts.{alias}.BuildNumber Numéro de build ou identificateur de commit.

Exemple pour Azure Pipelines : 20170112.1
Exemple pour Jenkins/TeamCity : 20170112.1
Exemple pour TFVC : Changeset 3
Exemple pour Git : 38629c964
Exemple pour GitHub : 38629c964
Release.Artifacts.{alias}.BuildId Identificateur de la build.

Exemple pour Azure Pipelines : 130
Exemple pour Jenkins/TeamCity : 130
Exemple pour GitHub : 38629c964d21fe405ef830b7d0220966b82c9e11
Release.Artifacts.{alias}.BuildURI URL de la build.

Exemple pour Azure Pipelines : vstfs://build-release/Build/130
Exemple pour GitHub : https://github.com/fabrikam/asp
Release.Artifacts.{alias}.SourceBranch Chemin d’accès complet et nom de la branche à partir de laquelle la source a été générée.

Exemple pour Azure Pipelines : refs/heads/main
Release.Artifacts.{alias}.SourceBranchName Nom uniquement de la branche à partir de laquelle la source a été générée.

Exemple pour Azure Pipelines : main
Release.Artifacts.{alias}.SourceVersion Commit qui a été généré.

Exemple pour Azure Pipelines : bc0044458ba1d9298cdc649cb5dcf013180706f7
Release.Artifacts.{alias}.Repository.Provider Type de référentiel à partir duquel la source a été générée.

Exemple pour Azure Pipelines : Git
Release.Artifacts.{alias}.RequestedForID Identificateur du compte qui a déclenché la build.

Exemple pour Azure Pipelines : 2f435d07-769f-4e46-849d-10d1ab9ba6ab
Release.Artifacts.{alias}.RequestedFor Nom du compte qui a demandé la build.

Exemple pour Azure Pipelines : Mateo Escobedo
Release.Artifacts.{alias}.Type Type de la source d’artefact, par exemple Build.

Exemple pour Azure Pipelines : Build
Exemple pour Jenkins : Jenkins
Exemple pour TeamCity : TeamCity
Exemple pour TFVC : TFVC
Exemple pour Git : Git
Exemple pour GitHub : GitHub
Release.Artifacts.{alias}.PullRequest.TargetBranch Chemin complet et nom de la branche cible d’une demande de tirage. Cette variable est initialisée uniquement si la mise en production est déclenchée via un flux de demande de tirage.

Exemple pour Azure Pipelines : refs/heads/main
Release.Artifacts.{alias}.PullRequest.TargetBranchName Nom uniquement de la branche cible d’une demande de tirage. Cette variable est initialisée uniquement si la mise en production est déclenchée via un flux de demande de tirage.

Exemple pour Azure Pipelines : main

Voir aussi Alias de la source d’artefact

Artefact principal

Vous désignez l’un des artefacts en tant qu’artefact principal dans un pipeline de mise en production. Pour l’artefact principal désigné, Azure Pipelines remplit les variables suivantes.

Nom de la variable Identique à
Build.DefinitionId Release.Artifacts.{Primary artifact alias}.DefinitionId
Build.DefinitionName Release.Artifacts.{Primary artifact alias}.DefinitionName
Build.BuildNumber Release.Artifacts.{Primary artifact alias}.BuildNumber
Build.BuildId Release.Artifacts.{Primary artifact alias}.BuildId
Build.BuildURI Release.Artifacts.{Primary artifact alias}.BuildURI
Build.SourceBranch Release.Artifacts.{Primary artifact alias}.SourceBranch
Build.SourceBranchName Release.Artifacts.{Primary artifact alias}.SourceBranchName
Build.SourceVersion Release.Artifacts.{Primary artifact alias}.SourceVersion
Build.Repository.Provider Release.Artifacts.{Primary artifact alias}.Repository.Provider
Build.RequestedForID Release.Artifacts.{Primary artifact alias}.RequestedForID
Build.RequestedFor Release.Artifacts.{Primary artifact alias}.RequestedFor
Build.Type Release.Artifacts.{Primary artifact alias}.Type
Build.PullRequest.TargetBranch Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranch
Build.PullRequest.TargetBranchName Release.Artifacts.{Primary artifact alias}.PullRequest.TargetBranchName

Utiliser les variables par défaut

Vous pouvez utiliser les variables par défaut de deux manières : en tant que paramètres pour des tâches dans un pipeline de mise en production ou dans vos scripts.

Vous pouvez utiliser une variable par défaut directement en tant qu’entrée dans une tâche. Par exemple, pour transmettre Release.Artifacts.{Artifact alias}.DefinitionName pour la source d’artefact dont l’alias est ASPNET4.CI à une tâche, utilisez $(Release.Artifacts.ASPNET4.CI.DefinitionName).

Utilisation de variables d’artefact dans les arguments d’une tâche de script PowerShell

Pour utiliser une variable par défaut dans votre script, vous devez d’abord remplacer . par _ dans les noms des variables par défaut. Par exemple, pour imprimer la valeur de la variable d’artefact Release.Artifacts.{Artifact alias}.DefinitionName pour la source d’artefact dont l’alias est ASPNET4.CI dans un script PowerShell, utilisez $env:RELEASE_ARTIFACTS_ASPNET4_CI_DEFINITIONNAME.

Utilisation de variables d’artefact dans un script PowerShell inline

Notez que le nom d’origine de l’alias de la source d’artefact ASPNET4.CI est remplacé par ASPNET4_CI.

Afficher les valeurs actuelles de l’ensemble des variables

  1. Ouvrez la vue des pipelines du résumé de la mise en production, puis choisissez la phase de votre choix. Dans la liste des étapes, choisissez Initialiser le travail.

    Ouverture du journal d’une mise en production

  2. Cette opération ouvre le journal de cette étape. Faites défiler vers le bas pour afficher les valeurs utilisées par l’agent pour ce travail.

    Afficher les valeurs des variables d’une mise en production

Exécuter une mise en production en mode débogage

Affichez des informations supplémentaires lors de l’exécution d’une mise en production et dans les fichiers journaux en exécutant la mise en production entière, ou uniquement les tâches d’une phase de mise en production individuelle, en mode débogage. Cela permet de résoudre les problèmes et les échecs.

  • Pour lancer le mode de débogage pour une mise en production entière, ajoutez une variable nommée System.Debug définie sur la valeur true sous l’onglet Variables d’un pipeline de mise en production.

  • Pour lancer le mode débogage pour une phase unique, ouvrez la boîte de dialogue Configurer la phase dans le menu contextuel de la phase et ajoutez une variable nommée System.Debug définie sur la valeur true à l’onglet Variables.

  • Vous pouvez également créer un groupe de variables contenant une variable nommée System.Debug définie sur la valeur true et lier ce groupe de variables à un pipeline de mise en production.

Conseil

En cas d’erreur liée à une connexion au service Azure RM, consultez Guide pratique pour résoudre les problèmes de connexion au service Azure Resource Manager.

Variables personnalisées

Les variables personnalisées peuvent être définies dans différentes étendues.

  • Partagez des valeurs dans l’ensemble des définitions d’un projet à l’aide de groupes de variables. Choisissez un groupe de variables quand vous avez besoin d’utiliser une valeur unique dans l’ensemble des définitions, phases et tâches d’un projet et que vous souhaitez modifier les valeurs à un seul emplacement. Vous définissez et gérez les groupes de variables sous l’onglet Bibliothèque.

  • Partagez des valeurs dans l’ensemble des phases à l’aide de variables de pipeline de mise en production. Choisissez une variable de pipeline de mise en production quand vous avez besoin d’utiliser une valeur unique dans l’ensemble des phases et tâches du pipeline de mise en production et que vous souhaitez modifier la valeur à un seul emplacement. Vous définissez et gérez ces variables sous l’onglet Variables d’un pipeline de mise en production. Dans la page Variables de pipeline, ouvrez la liste déroulante Étendue et sélectionnez « Mise en production ». Quand vous ajoutez une variable, elle est définie par défaut sur l’étendue de la mise en production.

  • Partagez des valeurs dans l’ensemble des tâches d’une phase spécifique à l’aide de variables de phase. Utilisez une variable de niveau phase pour les valeurs qui varient d’une phase à l’autre (et qui sont identiques pour l’ensemble des tâches d’une phase). Vous définissez et gérez ces variables sous l’onglet Variables d’un pipeline de mise en production. Dans la page Variables de pipeline, ouvrez la liste déroulante Étendue et sélectionnez la phase requise. Quand vous ajoutez une variable, définissez l’étendue sur l’environnement approprié.

L’utilisation de variables personnalisées au niveau du projet, du pipeline de mise en production et de l’étendue de la phase vous permet d’effectuer les tâches suivantes :

  • Évitez la duplication des valeurs afin de faciliter la mise à jour de l’ensemble des occurrences en une seule opération.

  • Stockez les valeurs sensibles de telle manière qu’elles ne soient ni visibles ni modifiables par les utilisateurs des pipelines de mise en production. Désignez une propriété de configuration en tant que variable sécurisée (secrète) en sélectionnant l’icône padlock (cadenas) à côté de la variable.

    Important

    Les valeurs des variables masquées (secrètes) sont stockées en toute sécurité sur le serveur et ne peuvent pas être consultées par les utilisateurs après l’enregistrement. Lors d’un déploiement, le service de mise en production Azure Pipelines déchiffre ces valeurs qui sont référencées par les tâches et les transmet à l’agent via un canal HTTPS sécurisé.

Notes

La création de variables personnalisées peut écraser les variables standard. Par exemple la variable d’environnement Path PowerShell. Si vous créez une variable personnalisée Path sur un agent Windows, elle écrase la variable $env:Path et PowerShell ne peut pas s’exécuter.

Utiliser des variables personnalisées

Pour utiliser des variables personnalisées dans les tâches de build et de mise en production, il suffit de placer le nom de la variable entre parenthèses et de le faire précéder d’un caractère $. Pour une variable nommée adminUserName par exemple, vous pouvez insérer la valeur actuelle de cette variable dans un paramètre d’une tâche en tant que $(adminUserName).

Notes

Les variables de différents groupes liés à un pipeline dans la même étendue (par exemple un travail ou une phase) sont en conflit et le résultat peut être imprévisible. Assurez-vous d’utiliser des noms différents pour les variables dans tous vos groupes de variables.

Définir et modifier vos variables dans un script

Pour définir ou modifier une variable à partir d’un script, utilisez la commande de journalisation task.setvariable. Notez que la valeur de la variable mise à jour est limitée au travail en cours d’exécution. Elle ne se propage pas dans les différents travaux ni phases. Les noms de variables sont transformés en majuscules, et les caractères « . » et «   » sont remplacés par « _ ».

Par exemple, Agent.WorkFolder devient AGENT_WORKFOLDER. Sous Windows, vous y accédez en tant que %AGENT_WORKFOLDER% ou $env:AGENT_WORKFOLDER. Sur Linux et macOS, vous utilisez $AGENT_WORKFOLDER.

Conseil

Vous pouvez exécuter un script sur ce qui suit :

Script Batch

Définir les variables sauce et secret.Sauce

@echo ##vso[task.setvariable variable=sauce]crushed tomatoes
@echo ##vso[task.setvariable variable=secret.Sauce;issecret=true]crushed tomatoes with garlic

Lire les variables

Arguments

"$(sauce)" "$(secret.Sauce)"

Script

@echo off
set sauceArgument=%~1
set secretSauceArgument=%~2
@echo No problem reading %sauceArgument% or %SAUCE%
@echo But I cannot read %SECRET_SAUCE%
@echo But I can read %secretSauceArgument% (but the log is redacted so I do not spoil
     the secret)

Sortie de la console après lecture des variables :

No problem reading crushed tomatoes or crushed tomatoes
But I cannot read 
But I can read ******** (but the log is redacted so I do not spoil the secret)