Variables de mise en production et d’artefacts classiques
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)
.
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
.
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
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.
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.
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 valeurtrue
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 valeurtrue
à l’onglet Variables.Vous pouvez également créer un groupe de variables contenant une variable nommée
System.Debug
définie sur la valeurtrue
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 (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
.
La valeur de variable mise à jour est étendue au travail en cours d’exécution et ne circule pas entre les travaux ou les étapes.
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
.
Sur Windows, vous accédez à cette variable 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 :
- Agent Windows à l’aide d’une tâche de script Batch ou d’une tâche de script PowerShell.
- Agent macOS ou Linux à l’aide d’une tâche de script Shell.
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)