Agents Windows autohébergés

Azure DevOps Services

Pour générer et déployer Windows, Azure et d’autres solutions Visual Studio, il vous faut au moins un agent Windows. Les agents Windows peuvent également générer des applications Java et Android.

Cet article fournit des conseils pour l'utilisation du logiciel agent 3.x avec Azure DevOps Services et les versions actuelles d'Azure DevOps Server. Pour obtenir une liste des versions d'Azure DevOps Server qui prennent en charge le logiciel agent 3.x, consultez la section Le logiciel agent 3.x est-il pris en charge par Azure DevOps Server?

Remarque

Cet article explique comment configurer un agent autohébergé. Si vous utilisez Azure DevOps Services et qu’un agent hébergé par Microsoft répond à vos besoins, vous pouvez ignorer la configuration d’un agent Windows autohébergé.

Présentation des agents

Si vous savez déjà ce qu’est un agent et comment il fonctionne, n’hésitez pas à passer directement aux sections suivantes. Toutefois, si vous souhaitez en savoir plus sur ce qu’ils font et sur leur fonctionnement, consultez Agents Azure Pipelines.

Vérifier les conditions préalables

Vérifiez que votre machine répond aux prérequis suivants :

  • Version du système d'exploitation
    • Système d'exploitation client
      • Windows 7 SP1 ESU
      • Windows 8.1
      • Windows 10
      • Windows 11
    • Système d'exploitation du serveur
      • Windows Server 2012 ou version ultérieure
  • Le logiciel agent installe sa propre version de .NET, il n'y a donc aucune condition préalable .NET.
  • PowerShell 3.0 (ou version ultérieure)
  • Subversion : si vous partez d’un référentiel Subversion, vous devez installer le client Subversion sur l’ordinateur.
  • (Recommandé) Outils de build Visual Studio (2015 ou version ultérieure)

Il est recommandé d’exécuter manuellement le programme d’installation de l’agent la première fois. Quand vous aurez compris comment fonctionnement les agents ou que vous souhaiterez automatiser la configuration de nombreux agents, envisagez d’utiliser la configuration sans assistance.

Spécifications matérielles

Les spécifications matérielles de vos agents varient en fonction de vos besoins, de la taille de l’équipe, etc. Il n’est pas possible de fournir des recommandations générales applicables à tout le monde. À titre de référence, l’équipe Azure DevOps génère le code des agents hébergés à l’aide de pipelines qui utilisent des agents hébergés. D’un autre côté, la majeure partie du code Azure DevOps est construite par des machines de classe serveur à 24 cœurs exécutant chacune quatre agents auto-hébergés.

Préparer les autorisations

Sécurité des informations pour les agents autohébergés

L’utilisateur qui configure l’agent a besoin d’autorisations d’administrateur de pool, mais pas l’utilisateur qui exécute l’agent.

Les dossiers contrôlés par l’agent doivent être limités au plus petit nombre possible d’utilisateurs, car ils contiennent des données secrètes qui risqueraient d'être déchiffrées ou exfiltrées.

L’agent Azure Pipelines est un produit logiciel conçu pour exécuter le code qu’il télécharge à partir de sources externes. Par nature, il peut être la cible d’attaques par exécution de code à distance.

Par conséquent, il est important de prendre en compte le modèle de menace entourant chaque utilisation individuelle des agents Pipelines pour effectuer le travail, et de décider quelles sont les autorisations minimales qui pourraient être accordées à l’utilisateur exécutant l’agent, à la machine sur laquelle l’agent s’exécute, aux utilisateurs qui ont un accès en écriture à la définition de pipeline, aux dépôts Git où le yaml est stocké, ou encore le groupe d’utilisateurs qui contrôlent l’accès au pool pour les nouveaux pipelines.

L’identité qui exécute l’agent doit, dans la mesure du possible, être différente de l’identité possédant des autorisations pour connecter l’agent au pool. L’utilisateur qui génère les informations d’identification (et d’autres fichiers liés à l’agent) est différent de celui qui doit les lire. Par sécurité, il convient donc de réfléchir scrupuleusement à l’accès accordé à l’ordinateur agent lui-même et aux dossiers d’agent contenant des fichiers sensibles tels que des journaux et des artefacts.

Il est judicieux d’accorder l’accès au dossier de l’agent uniquement aux administrateurs DevOps et à l’identité utilisateur exécutant le processus de l’agent. Les administrateurs peuvent avoir besoin d’investiguer le système de fichiers pour comprendre les échecs de build ou obtenir des fichiers journaux afin de signaler les échecs Azure DevOps.

Déterminer l’utilisateur à utiliser

Vous devez inscrire l’agent (une seule fois). Ces étapes doivent être effectuées par une personne disposant de l’autorisation d’administration de la file d’attente d’agents. L’agent n’utilisera pas les informations d’identification de cette personne pour les opérations quotidiennes, mais ces informations sont nécessaires pour effectuer l’inscription. Apprenez-en davantage sur le mode de communication des agents.

Vérifier que l’utilisateur dispose d’une autorisation

Vérifiez que le compte d’utilisateur que vous allez utiliser est autorisé à inscrire l’agent.

Si l’utilisateur est propriétaire d’organisation Azure DevOps ou administrateur TFS ou Azure DevOps Server, arrêtez-vous ici. Vous avez l’autorisation.

Sinon :

  1. Ouvrez un navigateur et accédez à l’onglet Pools d’agents pour votre organisation Azure Pipelines ou votre serveur Azure DevOps Server ou TFS :

    1. Connectez-vous à votre organisation (https://dev.azure.com/{yourorganization}).

    2. Choisissez Azure DevOps, Paramètres de l’organisation.

      Choisissez Paramètres de l’organisation.

    3. Choisissez Pools d’agents.

      Choisissez l’onglet Pools d’agents.

    1. Connectez-vous à votre collection de projets (http://your-server/DefaultCollection).

    2. Choisissez Azure DevOps, Paramètres de la collection.

      Choisissez Paramètres de la collection.

    3. Choisissez Pools d’agents.

      Choisissez Pools d’agents.

    1. Choisissez Azure DevOps, Paramètres de la collection.

      Paramètres de la collection, 2019.

    2. Choisissez Pools d’agents.

      Choisissez Pools d’agents, 2019.

  2. Sélectionnez le pool à droite de la page, puis cliquez sur Sécurité.

  3. Si le compte d’utilisateur que vous envisagez d’utiliser n’est pas affiché, demandez à un administrateur de l’ajouter. L’administrateur peut être un administrateur de pool d’agents, un propriétaire d’organisation Azure DevOps ou un administrateur TFS ou Azure DevOps Server.

    S’il s’agit d’un agent de groupe de déploiement, l’administrateur peut être un administrateur de groupe de déploiement, un propriétaire d’organisation Azure DevOps ou un administrateur TFS ou Azure DevOps Server.

    Vous pouvez ajouter un utilisateur au rôle d’administrateur de groupe de déploiement dans l’onglet Sécurité de la page Groupes de déploiement dans Azure Pipelines.

Notes

Si vous voyez un message du type Nous n’avons pas pu ajouter l’identité. Essayez une autre identité., vous avez probablement suivi les étapes plus haut pour un propriétaire d’organisation ou un administrateur TFS ou Azure DevOps Server. Vous n’avez rien à faire : vous disposez déjà de l’autorisation d’administrer le pool d’agents.

Télécharger et configurer l’agent

Azure Pipelines

  1. Connectez-vous à la machine avec le compte pour lequel vous avez préparé les autorisations, comme expliqué plus haut.

  2. Dans votre navigateur web, connectez-vous à Azure Pipelines et accédez à l’onglet Pools d’agents :

    1. Connectez-vous à votre organisation (https://dev.azure.com/{yourorganization}).

    2. Choisissez Azure DevOps, Paramètres de l’organisation.

      Choisissez Paramètres de l’organisation.

    3. Choisissez Pools d’agents.

      Choisissez l’onglet Pools d’agents.

    1. Connectez-vous à votre collection de projets (http://your-server/DefaultCollection).

    2. Choisissez Azure DevOps, Paramètres de la collection.

      Choisissez Paramètres de la collection.

    3. Choisissez Pools d’agents.

      Choisissez Pools d’agents.

    1. Choisissez Azure DevOps, Paramètres de la collection.

      Paramètres de la collection, 2019.

    2. Choisissez Pools d’agents.

      Choisissez Pools d’agents, 2019.

  3. Sélectionnez le pool Par défaut, sélectionnez l’onglet Agents, puis choisissez Nouvel agent.

  4. Dans la boîte de dialogue Obtenir l’agent, choisissez Windows.

  5. Dans le volet gauche, sélectionnez l’architecture de processeur de la version du système d’exploitation Windows installée sur votre machine. La version de l’agent x64 est destinée à Windows 64 bits et la version x86 à Windows 32 bits. Si vous ne savez pas quelle version de Windows est installée, suivez ces instructions pour la déterminer.

  6. Dans le volet de droite, cliquez sur le bouton Télécharger.

  7. Suivez les instructions fournies sur la page pour télécharger l’agent.

  8. Décompressez l’agent dans le répertoire de votre choix. Veillez à ce que le chemin du répertoire ne contienne aucun espace, car les outils et les scripts ne gèrent pas toujours correctement les espaces d’échappement. Par exemple, le dossier C:\agents est recommandé. L’extraction dans le dossier de téléchargement ou dans d’autres dossiers utilisateur peut entraîner des problèmes d’autorisation.

Important

Nous vous recommandons vivement de configurer l’agent dans une fenêtre PowerShell avec élévation de privilèges. C’est obligatoire si vous souhaitez le configurer en tant que service.

Vous ne devez pas utiliser Windows PowerShell ISE pour configurer l’agent.

Important

Pour des raisons de sécurité, nous vous recommandons vivement de vérifier que le dossier agents (C:\agents) est modifiable uniquement par des administrateurs.

Notes

Évitez d’utiliser des interpréteurs de commandes basés sur mintty (par exemple git-bash) pour la configuration de l’agent. Mintty n’est pas entièrement compatible avec l’API Windows d’entrée/sortie native (voici quelques informations à ce sujet) et nous ne pouvons pas garantir que le script d’installation fonctionnera correctement dans ce cas.

Installer l’agent

  1. Ouvrez une fenêtre PowerShell avec des privilèges élevés et définissez l’emplacement où vous avez décompressé l'agent.

    cd C:\agents 
    
    
  2. Exécutez config.cmd. Vous devez alors répondre à une série de questions pour configurer l’agent.

    .\config.cmd
    
    

URL du serveur

Quand le programme d’installation demande l’URL de votre serveur, pour Azure DevOps Services, répondez https://dev.azure.com/{your-organization}.

Lorsque l'installation vous demande l'URL de votre serveur, pour Azure DevOps Server, répondez https://{my-server}/{my-collection}.

Type d'authentification de configuration de l'agent

Lorsque vous enregistrez un agent, choisissez l’un des types d’authentification suivants, et le programme d’installation vous demandera les informations supplémentaires spécifiques requises pour chaque type d’authentification. Pour plus d'informations, consultez Options d'authentification de l'agent auto-hébergé.

  • Jeton d’accès personnel
  • Connectez-vous alternativement à Azure DevOps Server ou TFS à l’aide de l’authentification De base. Lorsque vous sélectionnez Alternative, vous serez invité à fournir vos informations d'identification.

Les agents Windows disposent des deux options d'authentification supplémentaires suivantes sur Azure DevOps Server et TFS.

  • Négocier Connexion à TFS en tant qu’utilisateur autre que l’utilisateur connecté selon un schéma d’authentification Windows tel que NTLM ou Kerberos. Quand vous sélectionnez Négocier, vous êtes invité à entrer vos informations d’identification.
  • Intégré (par défaut) Connexion d’un agent Windows à TFS avec les informations d’identification de l’utilisateur connecté selon un schéma d’authentification Windows tel que NTLM ou Kerberos. Quand vous choisissez cette méthode, vos informations d’identification ne vous sont pas demandées.

Important

Votre serveur doit être configuré pour prendre en charge la méthode d'authentification afin d'utiliser l'authentification alternative, négociée ou intégrée.

La méthode d'authentification utilisée pour enregistrer l'agent est utilisée uniquement lors de l'enregistrement de l'agent. Pour en savoir plus sur la manière dont les agents communiquent avec Azure Pipelines après l'inscription, consultez Communication avec Azure Pipelines ou TFS.

Choix entre le mode interactif et le mode service

Pour obtenir de l’aide sur le choix entre l’exécution de l’agent en mode interactif ou en tant que service, consultez Agents : Interactif ou service.

Si vous choisissez de l’exécuter en tant que service (recommandé), le nom d’utilisateur doit comporter 20 caractères maximum.

Exécuter l’agent

Exécuter de manière interactive

Si vous avez configuré l’agent de manière interactive, exécutez la commande suivante pour démarrer l’agent.

.\run.cmd

Pour redémarrer l’agent, appuyez sur Ctrl+C pour arrêter l’agent, puis exécutez run.cmd pour le redémarrer.

Remarque

Si vous exécutez l’agent depuis PowerShell Core pour exécuter des tâches Windows PowerShell, votre pipeline peut échouer avec une erreur telle que Error in TypeData "System.Security.AccessControl.ObjectSecurity": The member is already present. Cela est dû au fait que Windows PowerShell hérite de la variable d’environnement PSModulePath, qui inclut les emplacements des modules PowerShell Core, depuis son processus parent.

Pour contourner cela, vous pouvez définir le paramètre AZP_AGENT_CLEANUP_PSMODULES_IN_POWERSHELL de l’agent à true dans le pipeline. Cela permettra à l’agent de réinitialiser PSModulePath avant d’exécuter les tâches.

variables:
 AZP_AGENT_CLEANUP_PSMODULES_IN_POWERSHELL: "true"

Si cette solution de contournement ne résout pas votre problème, ou si vous devez utiliser des emplacements de modules personnalisés, vous pouvez définir la variable $Env:PSModulePath selon vos besoins dans votre fenêtre PowerShell Core avant d’exécuter l’agent.

Exécuter une fois

Vous pouvez également choisir d’accepter un seul travail et de quitter l’agent. Pour exécuter cette configuration, utilisez la commande suivante.

.\run.cmd --once

Les agents dans ce mode acceptent un seul travail, puis s’arrêtent normalement (ce qui est utile pour une exécution dans Docker sur un service comme Azure Container Instances).

Exécuter en tant que service

Si vous avez configuré l’agent pour qu’il s’exécute en tant que service, il démarre automatiquement. Vous pouvez voir et contrôler l’état d’exécution de l’agent dans le composant logiciel enfichable de services. Exécutez services.msc et recherchez l’un des éléments suivants :

  • « Agent Azure Pipelines (nom de votre agent) »
  • « Agent VSTS (nom de votre agent) »
  • « vstsagent. (nom de l’organisation).(nom de votre agent) »

Remarque

Pour permettre une flexibilité accrue dans le contrôle d’accès d’un agent s’exécutant en tant que service, il est possible de configurer le type de SID du service de l’agent en tant que [SERVICE_SID_TYPE_UNRESTRICTED] via un indicateur ou une invite pendant le flux de configuration interactif. Par défaut, le service d’agent est configuré avec SERVICE_SID_TYPE_NONE.

Pour en savoir plus sur les types de SID , veuillez consulter cette documentation.

Pour redémarrer l’agent, cliquez avec le bouton droit sur l’entrée et choisissez Redémarrer.

Notes

Si vous devez modifier le compte d’ouverture de session de l’agent, ne le faites pas avec le composant logiciel enfichable de services. Consultez plutôt les informations ci-dessous pour reconfigurer l’agent.

Pour utiliser votre agent, exécutez un travail en utilisant le pool de l’agent. Si vous n’avez pas choisi un autre pool, votre agent se trouve dans le pool Par défaut.

Remplacer un agent

Pour remplacer un agent, suivez à nouveau les étapes décrites dans la section Télécharger et configurer l’agent.

Quand vous configurez un agent avec le même nom qu’un agent existant, vous êtes invité à remplacer l’agent existant. Si vous répondez Y, veillez à supprimer l’agent (voir ci-dessous) que vous remplacez. Sinon, après quelques minutes de conflits, l’un des agents s’arrête.

Supprimer et reconfigurer un agent

Pour supprimer l’agent :

.\config remove

Après avoir supprimé l’agent, vous pouvez le configurer à nouveau.

Configuration sans assistance

L’agent peut être configuré à partir d’un script sans intervention humaine. Vous devez transférer --unattended et les réponses à toutes les questions.

Pour configurer un agent, il doit connaître l’URL de votre organisation ou collection et les informations d’identification d’une personne autorisée à configurer des agents. Toutes les autres réponses sont facultatives. Tout paramètre de ligne de commande peut être spécifié avec une variable d’environnement à la place : spécifiez son nom en majuscules et faites-le précéder de VSTS_AGENT_INPUT_. Par exemple, VSTS_AGENT_INPUT_PASSWORD au lieu de spécifier --password.

Options obligatoires

  • --unattended : La configuration de l’agent ne demande pas d’informations et tous les paramètres doivent être spécifiés sur la ligne de commande
  • --url <url> : URL du serveur. Par exemple : https://dev.azure.com/myorganization ou http://my-azure-devops-server:8080/tfs
  • --auth <type> : Type d’authentification. Les valeurs valides sont les suivantes :
    • pat (Jeton d’accès personnel)
    • SP (Service Principal) (Nécessite la version 3.227.1 ou plus récente de l’agent)
    • negotiate (Kerberos ou NTLM)
    • alt (Authentification de base)
    • integrated (Informations d’identification Windows par défaut)

Options d’authentification

  • Si vous avez choisi --auth pat :
    • --token <token> : Spécifie votre jeton d’accès personnel
    • Vous pouvez également transmettre un jeton OAuth 2.0 en tant que paramètre --token.
  • Si vous avez choisi --auth negotiate ou --auth alt :
    • --userName <userName> : Spécifie un nom d’utilisateur Windows au format domain\userName ou userName@domain.com
    • --password <password> : Spécifie un mot de passe
  • Si vous avez choisi --auth SP :
    • --clientID <clientID> : spécifie l’ID client du Service Principal ayant accès à l’enregistrement des agents
    • --tenantId <tenantID> : spécifie l’ID du client dans lequel le Service Principal est enregistré
    • --clientSecret <clientSecret> : spécifie le secret client du Service Principal
    • Veuillez consulter la section Enregistrer un agent en utilisant un service principal pour plus d’informations.

Noms de pool et d’agent

  • --pool <pool> : Nom du pool que l’agent doit joindre
  • --agent <agent> : Nom de l’agent
  • --replace : Remplacer l’agent dans un pool. Si un autre agent écoute sous le même nom, il commence à échouer avec un conflit

Configuration de l’agent

  • --work <workDirectory> : Répertoire de travail dans lequel les données de travail sont stockées. Le répertoire par défaut est _work à la racine du répertoire de l’agent. Le répertoire de travail appartient à un agent donné et ne doit pas être partagé entre plusieurs agents.
  • --acceptTeeEula : Accepter le Contrat de licence d’utilisateur final Team Explorer Everywhere (macOS et Linux uniquement)
  • --disableloguploads : Ne pas envoyer (en streaming ou non) la sortie de journal de la console au serveur. Vous pouvez, dans ce cas, la récupérer à partir du système de fichiers de l’hôte de l’agent quand le travail est terminé.

Démarrage Windows uniquement

  • --runAsService : Configure l’agent pour qu’il s’exécute comme service Windows (nécessite une autorisation d’administrateur)
  • --runAsAutoLogon : Configure l’ouverture de session automatique et exécute l’agent au démarrage (nécessite une autorisation d’administrateur)
  • --windowsLogonAccount <account> : Utilisé avec --runAsService ou --runAsAutoLogon pour spécifier le nom d’utilisateur Windows au format domain\userName ou userName@domain.com
  • --windowsLogonPassword <password> : Utilisé avec --runAsService ou --runAsAutoLogon pour spécifier le mot de passe d’ouverture de session Windows (non requis pour les comptes de service géré de groupe et les comptes Windows intégrés tels que 'NT AUTHORITY\NETWORK SERVICE')
  • --enableservicesidtypeunrestricted : utilisé avec --runAsService pour configurer l’agent avec le type de SID de service comme SERVICE_SID_TYPE_UNRESTRICTED (nécessite une autorisation d’administrateur)
  • --overwriteAutoLogon : Utilisé avec --runAsAutoLogon pour remplacer l’ouverture de session automatique existante sur la machine
  • --noRestart : Utilisé avec --runAsAutoLogon pour empêcher l’hôte de redémarrer à la fin de la configuration de l’agent

Résolution des problèmes de configuration de l’agent avec l’option runAsAutoLogon

La configuration de l’agent avec l’option runAsAutoLogon exécute l’agent après chaque redémarrage de la machine. Effectuez les étapes suivantes si l’agent n’est pas exécuté après le redémarrage de la machine.

Si l’agent était déjà configuré sur la machine

Avant de reconfigurer l’agent, il est nécessaire de supprimer l’ancienne configuration de l’agent. Pour cela, essayez d’exécuter cette commande dans le dossier de l’agent :

.\config.cmd remove --auth 'PAT' --token '<token>'

Vérifiez si l’agent a été supprimé de votre pool d’agents après l’exécution de la commande :

<Azure DevOps organization> / <Project> / Settings / Agent pools / <Agent Pool> / Agents

Supprimez manuellement l’agent de votre pool d’agents s’il n’a pas été supprimé par l’exécution de la commande.

Essayez ensuite de reconfigurer l’agent en exécutant cette commande dans le dossier de l’agent :

.\config.cmd --unattended --agent '<agent-name>' --pool '<agent-pool-name>' --url '<azure-dev-ops-organization-url>' --auth 'PAT' --token '<token>' --runAsAutoLogon --windowsLogonAccount '<domain\user-name>' --windowsLogonPassword '<windows-password>'

Spécifiez le nom de l’agent (n’importe quel nom unique spécifique) et vérifiez si cet agent apparaît dans votre pool d’agents après la reconfiguration.

Il est largement préférable de décompresser une archive d’agent (qui peut être téléchargée ici) et d’exécuter cette commande dans le dossier du nouvel agent décompressé.

Vérifier si la clé de Registre Windows est enregistrée et sauvegardée correctement

Exécutez la commande whoami /user pour obtenir le <sid>. Ouvrez Registry Editor et suivez le chemin :

Computer\HKEY_USERS\<sid>\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

Vérifiez la présence de la clé VSTSAgent. Supprimez cette clé si elle existe, puis fermez Registry Editor et configurez l’agent en exécutant la commande .\config.cmd (sans arguments) dans le dossier de l’agent. Avant de répondre à la question Enter Restart the machine at a later time?, ouvrez de nouveau Registry Editor et vérifiez si la clé VSTSAgent est apparue. Appuyez sur Enter pour répondre à la question et vérifiez si la clé VSTSAgent reste à sa place après le redémarrage de la machine.

Vérifier si les clés de Registre Windows fonctionnent correctement sur votre machine

Créez un fichier autorun.cmd contenant la ligne suivante : echo "Hello from AutoRun!". Ouvrez Registry Editor et créez, dans le chemin plus haut, une nouvelle paire clé-valeur avec la clé AutoRun et la valeur

C:\windows\system32\cmd.exe /D /S /C start "AutoRun" "D:\path\to\autorun.cmd"

Redémarrez votre machine. Si vous ne voyez pas de fenêtre de console avec le message Hello from AutoRun!, cela indique un problème avec les clés de Registre Windows.

Groupe de déploiement uniquement

  • --deploymentGroup : Configure l’agent comme agent de groupe de déploiement
  • --deploymentGroupName <name> : Utilisé avec --deploymentGroup pour spécifier le groupe de déploiement que l’agent doit joindre
  • --projectName <name> : Utilisé avec --deploymentGroup pour définir le nom du projet
  • --addDeploymentGroupTags : Utilisé avec --deploymentGroup pour indiquer que des étiquettes de groupe de déploiement doivent être ajoutées
  • --deploymentGroupTags <tags> : Utilisé avec --addDeploymentGroupTags pour spécifier la liste d’étiquettes séparées par des virgules pour l’agent de groupe de déploiement, par exemple « web, db »

Environnements uniquement

  • --addvirtualmachineresourcetags : Utilisé pour indiquer que des étiquettes de ressource d’environnement doivent être ajoutées
  • --virtualmachineresourcetags <tags> : Utilisé avec --addvirtualmachineresourcetags pour spécifier la liste d’étiquettes séparées par des virgules pour l’agent de ressource d’environnement, par exemple, « web, db »

.\config --help liste toujours les réponses obligatoires et facultatives les plus récentes.

Diagnostics

Si vous rencontrez des problèmes avec votre agent auto-hébergé, vous pouvez essayer d’exécuter des diagnostics. Après la configuration de l’agent :

.\run --diagnostics

Cela s’exécute au travers d’une suite de diagnostic qui peut vous aider à résoudre le problème. La fonctionnalité de diagnostic est disponible à partir de la version 2.165.0 de l’agent.

Diagnostics réseau pour les agents autohébergés

Définissez la valeur de Agent.Diagnostic à true pour collecter des journaux supplémentaires qui peuvent être utilisés pour résoudre les problèmes réseau pour les agents auto-hébergés. Pour plus d'informations, consultez Diagnostics réseau pour les agents auto-hébergés

Aide sur d’autres options

Pour obtenir des informations sur les autres options :

.\config --help

L’aide fournit des informations sur les alternatives d’authentification et la configuration sans assistance.

Fonctionnalités

Les capacités de votre agent sont cataloguées et publiées dans le pool pour que seules les builds et les mises en production qu’il peut gérer lui soient attribuées. Consultez Capacités des agents de build et de mise en production.

Dans de nombreux cas, après avoir déployé un agent, vous devez installer des logiciels ou des utilitaires. En règle générale, vous devez installer sur vos agents les logiciels et outils que vous utilisez sur votre machine de développement.

Par exemple, si votre build inclut la tâche npm, la build ne s’exécute pas, sauf si le pool inclut un agent de build sur lequel npm est installé.

Important

Les fonctionnalités incluent toutes les variables d’environnement et les valeurs définies à l’exécution de l’agent. Si l’une de ces valeurs change pendant l’exécution de l’agent, celui-ci doit être redémarré pour récupérer les nouvelles valeurs. Après avoir installé de nouveaux logiciels sur un agent, vous devez le redémarrer pour que la nouvelle capacité s’affiche dans le pool et que la build puisse s’exécuter.

Si vous souhaitez exclure des variables d’environnement en tant que capacités, vous pouvez les désigner en définissant une variable d’environnement VSO_AGENT_IGNORE avec une liste des variables à ignorer séparées par des virgules.

Questions fréquentes (FAQ)

Quelle version de Git mon agent exécute-t-il ?

Par défaut, l’agent Windows utilise la version de Git fournie avec le logiciel de l’agent. Il s’agit de la version recommandée par Microsoft. Néanmoins, vous disposez de plusieurs options pour remplacer ce comportement par défaut et choisir la version de Git que l’ordinateur de l’agent a installée dans le chemin.

Pour connaître la version de Git utilisée par un pipeline, vous pouvez examiner les journaux d’une étape checkout dans votre pipeline, comme dans l’exemple suivant :

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

Comment vérifier que je dispose de la dernière version de l’agent ?

  1. Accédez à l’onglet Pools d’agents :

    1. Connectez-vous à votre organisation (https://dev.azure.com/{yourorganization}).

    2. Choisissez Azure DevOps, Paramètres de l’organisation.

      Choisissez Paramètres de l’organisation.

    3. Choisissez Pools d’agents.

      Choisissez l’onglet Pools d’agents.

    1. Connectez-vous à votre collection de projets (http://your-server/DefaultCollection).

    2. Choisissez Azure DevOps, Paramètres de la collection.

      Choisissez Paramètres de la collection.

    3. Choisissez Pools d’agents.

      Choisissez Pools d’agents.

    1. Choisissez Azure DevOps, Paramètres de la collection.

      Paramètres de la collection, 2019.

    2. Choisissez Pools d’agents.

      Choisissez Pools d’agents, 2019.

  2. Cliquez sur le pool qui contient l’agent.

  3. Vérifiez que l’agent est activé.

  4. Accédez à l’onglet Capacités :

    1. Sous l’onglet Pools d’agents, sélectionnez le pool d’agents souhaité.

      Dans les pools d’agents, sélectionnez le pool d’agents souhaité.

    2. Sélectionnez Agents et choisissez l’agent souhaité.

      Sélectionnez Agents et choisissez l’agent.

    3. Choisissez l’onglet Fonctionnalités.

      Choisissez l’onglet Fonctionnalités.

      Notes

      Les agents hébergés par Microsoft n’affichent pas de fonctionnalités système. Pour obtenir la liste des logiciels installés sur des agents hébergés par Microsoft, consultez Utiliser un agent hébergé par Microsoft.

    1. Sous l’onglet Pools d’agents, sélectionnez le pool souhaité.

      Sélectionnez le pool souhaité.

    2. Sélectionnez Agents et choisissez l’agent souhaité.

      Sélectionnez Agents et choisissez l’agent souhaité.

    3. Choisissez l’onglet Fonctionnalités.

      Onglet Capacités de l’agent.

    1. Sous l’onglet Pools d’agents, sélectionnez le pool souhaité.

      Sélectionnez l’onglet souhaité, 2019.

    2. Sélectionnez Agents et choisissez l’agent souhaité.

      Choisissez l’agent souhaité, 2019.

    3. Choisissez l’onglet Fonctionnalités.

      Sélectionnez l’onglet Fonctionnalités, 2019.

  5. Recherchez la capacité Agent.Version. Vous pouvez vérifier cette valeur en la comparant à la dernière version publiée de l’agent. Consultez Agent Azure Pipelines et recherchez le numéro de version le plus élevé dans la page.

  6. Chaque agent est mis à jour automatiquement quand il exécute une tâche nécessitant une version plus récente de l’agent. Si vous souhaitez mettre à jour manuellement certains agents, cliquez avec le bouton droit sur le pool, puis sélectionnez Mettre à jour tous les agents.

Puis-je mettre à jour mes agents qui font partie d’un pool Azure DevOps Server ?

Oui. À partir d’Azure DevOps Server 2019, vous pouvez configurer votre serveur pour rechercher les fichiers de package d’agent sur un disque local. Cette configuration remplace la version par défaut fournie avec le serveur au moment de sa publication. Ce scénario s’applique également quand le serveur n’a pas accès à Internet.

  1. À partir d’un ordinateur disposant d’un accès Internet, téléchargez la dernière version des fichiers de package d’agent (au format .zip ou .tar.gz) à partir de la page GitHub des versions d’agent Azure Pipelines.

  2. Transférez les fichiers de package téléchargés vers chaque couche Application d’Azure DevOps Server avec la méthode de votre choix (par exemple, lecteur USB, transfert réseau, etc.). Placez les fichiers de l’agent dans le dossier suivant :

  • Windows : %ProgramData%\Microsoft\Azure DevOps\Agents
  • Linux : usr/share/Microsoft/Azure DevOps/Agents
  • MacOS : usr/share/Microsoft/Azure DevOps/Agents

Créez le dossier Agents s’il n’est pas présent.

  1. Vous êtes prêt à commencer ! Votre serveur Azure DevOps Server utilise désormais les fichiers locaux à chaque mise à jour des agents. Chaque agent est mis à jour automatiquement quand il exécute une tâche nécessitant une version plus récente de l’agent. Toutefois, si vous souhaitez mettre à jour manuellement certains agents, cliquez avec le bouton droit sur le pool, puis choisissez Mettre à jour tous les agents.

J’exécute un pare-feu et mon code se trouve dans Azure Repos. Avec quelles URL l’agent doit-il communiquer ?

Si vous exécutez un agent dans un réseau sécurisé derrière un pare-feu, vérifiez qu’il peut démarrer une communication avec les URL et adresses IP suivantes.

URL du domaine Description
https://{organization_name}.pkgs.visualstudio.com API d’empaquetage Azure DevOps pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.visualstudio.com Pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.vsblob.visualstudio.com Télémétrie Azure DevOps pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com Services Release Management pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.vssps.visualstudio.com Services de plateforme Azure DevOps pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com Services de gestion des tests Azure DevOps pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://*.blob.core.windows.net Azure Artifacts
https://*.dev.azure.com Pour les organisations utilisant le domaine dev.azure.com
https://*.vsassets.io Azure Artifacts avec CDN
https://*.vsblob.visualstudio.com Télémétrie Azure DevOps pour les organisations utilisant le domaine dev.azure.com
https://*.vssps.visualstudio.com Services de plateforme Azure DevOps pour les organisations utilisant le domaine dev.azure.com
https://*.vstmr.visualstudio.com Services de gestion des tests Azure DevOps pour les organisations utilisant le domaine dev.azure.com
https://app.vssps.visualstudio.com Pour les organisations utilisant le domaine {organization_name}.visualstudio.com
https://dev.azure.com Pour les organisations utilisant le domaine dev.azure.com
https://login.microsoftonline.com Connexion Microsoft Entra
https://management.core.windows.net API de gestion Azure
https://vstsagentpackage.azureedge.net Package d’agent

Pour garantir que votre organisation fonctionne avec les restrictions de pare-feu ou d’IP existantes, vérifiez que dev.azure.com et *dev.azure.com sont ouverts et mettez à jour vos IP sur liste verte pour y inclure les adresses IP suivantes, en fonction de votre version IP. Si les adresses IP 13.107.6.183 et 13.107.9.183 sont déjà sur votre liste verte, conservez-les, car vous n’avez pas besoin de les supprimer.

Plages IPv4

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

Plages IPv6

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

Notes

Pour plus d’informations sur les adresses autorisées, consultez Connexions réseau et listes d’adresses autorisées.

Comment exécuter l’agent avec un certificat auto-signé ?

Remarque

L’exécution de l’agent avec un certificat auto-signé s’applique uniquement à Azure DevOps Server.

Exécuter l’agent avec un certificat auto-signé

Comment exécuter l’agent derrière un proxy web ?

Exécuter l’agent derrière un proxy web

Comment redémarrer l’agent ?

Si vous exécutez l'agent de manière interactive, consultez les instructions de redémarrage dans Exécuter de manière interactive. Si vous exécutez l'agent en tant que service, redémarrez l'agent en suivant les étapes décrites dans Exécuter en tant que service.

Comment définir des variables d’environnement différentes pour chaque agent ?

Créez un fichier .env sous le répertoire racine de l’agent, placez les variables d’environnement que vous souhaitez définir dans le fichier au format suivant, puis redémarrez l’agent.

MyEnv0=MyEnvValue0
MyEnv1=MyEnvValue1
MyEnv2=MyEnvValue2
MyEnv3=MyEnvValue3
MyEnv4=MyEnvValue4

Comment configurer l’agent de sorte qu’il contourne un proxy web et se connecte à Azure Pipelines ?

Si vous souhaitez que l’agent contourne votre proxy et se connecte directement à Azure Pipelines, vous devez configurer votre proxy web pour permettre à l’agent d’accéder aux URL suivantes.

Pour les organisations qui utilisent le domaine *.visualstudio.com :

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

Pour les organisations qui utilisent le domaine dev.azure.com :

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://vssps.dev.azure.com

Pour garantir que votre organisation fonctionne avec les restrictions de pare-feu ou d’IP existantes, vérifiez que dev.azure.com et *dev.azure.com sont ouverts et mettez à jour vos IP sur liste verte pour y inclure les adresses IP suivantes, en fonction de votre version IP. Si les adresses IP 13.107.6.183 et 13.107.9.183 sont déjà sur votre liste verte, conservez-les, car vous n’avez pas besoin de les supprimer.

Plages IPv4

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

Plages IPv6

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

Notes

Cette procédure permet à l’agent de contourner un proxy web. Votre pipeline et vos scripts de build doivent toujours gérer le contournement de votre proxy web pour chaque tâche et outil que vous exécutez dans votre build.

Par exemple, si vous utilisez une tâche NuGet, vous devez configurer votre proxy web pour prendre en charge le contournement de l’URL pour le serveur qui héberge le flux NuGet que vous utilisez.

J’utilise TFS et les URL dans les sections plus haut ne fonctionnent pas pour moi. Où puis-je obtenir de l’aide ?

Paramètres et sécurité des sites web

J’utilise TFS localement et je ne vois pas certaines de ces fonctionnalités. Pourquoi cela ne fonctionne-t-il pas ?

Certaines de ces fonctionnalités sont disponibles uniquement sur Azure Pipelines et ne sont pas encore disponibles localement. Certaines fonctionnalités sont disponibles localement si vous avez effectué une mise à niveau vers la dernière version de TFS.

Qu’est-ce que l’invite « enable SERVICE_SID_TYPE_UNRESTRICTED for agent service » ?

Quand vous configurez le logiciel agent sur Windows Server, vous pouvez spécifier l’identificateur de sécurité du service à partir de l’invite suivante.

Enter enable SERVICE_SID_TYPE_UNRESTRICTED for agent service (Y/N) (press enter for N)

Les versions précédentes du logiciel agent définissaient le type d’identificateur de sécurité de service sur SERVICE_SID_TYPE_NONE (valeur par défaut pour les versions actuelles de l’agent). Pour configurer le type d’identificateur de service de sécurité sur SERVICE_SID_TYPE_UNRESTRICTED, appuyez sur Y.

Pour plus d’informations, consultez Structure SERVICE_SID_INFO et Identificateurs de sécurité.