Agents macOS autohébergés

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

Pour créer et déployer des applications Xcode ou des projets Xamarin.iOS, vous avez besoin d'au moins un agent macOS. Cet agent peut également générer et déployer des applications Java et Android.

En savoir plus sur les 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

• Systèmes d'exploitation pris en charge
  • X64
    • macOS 10.15 « Catalina »
    • macOS 11.0 « Big Sur »
    • macOS 12.0 « Monterey »
    • macOS 13.0 « Ventura »
    • macOS 14.0 « Sonoma »
  • ARM64
    • macOS 11.0 « Big Sur »
    • macOS 12.0 « Monterey »
    • macOS 13.0 « Ventura »
    • macOS 14.0 « Sonoma »

• Git – Git 2.9.0 ou supérieur (dernière version recommandée – vous pouvez facilement l'installer avec Homebrew)

• .NET : le logiciel de l’agent s’exécute sur .NET 6, mais installe sa propre version de .NET, il n’existe donc aucun prérequis .NET.
• TFVC : si vous effectuez la génération à partir d’un référentiel TFVC, consultez Prérequis TFVC.

Préparer les autorisations

Si vous générez à partir d’un référentiel Subversion, vous devez installer le client Subversion sur l’ordinateur.

La première fois, vous devez exécuter la configuration de l’agent manuellement. Une fois que vous avez une idée du fonctionnement des agents ou si vous souhaitez automatiser la configuration de nombreux agents, envisagez d’utiliser la configuration sans assistance.

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.

      

   3. Choisissez Pools d’agents.

      

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

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

      

   3. Choisissez Pools d’agents.

      

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

      

   2. Choisissez Pools d’agents.

      

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.

Télécharger et configurer l’agent

URL du serveur

Type d'authentification

Lorsque vous enregistrez un agent, choisissez parmi les types d'authentification suivants et la configuration de l'agent vous invite à fournir 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é.

Effectuer l'exécution de manière interactive

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

Pour exécuter l’agent de manière interactive :

1. Si vous avez exécuté l’agent en tant que service, désinstallez le service.

2. Exécutez l'agent.

   ./run.sh
   

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

Pour utiliser votre agent, exécutez un travail à l’aide du pool de l’agent. Si vous n'avez pas choisi un autre pool, votre agent est placé dans le pool par défaut.

Exécuter une fois

Pour que les agents configurés s’exécutent de manière interactive, vous pouvez choisir qu’ils n’acceptent qu’un seul travail. Pour une exécution dans cette configuration :

./run.sh --once

Les agents dans ce mode n'acceptent qu'une seule tâche, puis s'arrêtent progressivement (utile pour s'exécuter sur un service comme Azure Container Instances).

Exécuter en tant que service lancé

Nous fournissons le script ./svc.sh pour vous permettre d’exécuter et de gérer votre agent en tant que service LaunchAgent launchd. Ce script est généré après la configuration de l’agent. Le service a accès à l’interface utilisateur pour exécuter vos tests d’interface utilisateur.

Jetons

Dans la section suivante, ces jetons sont remplacés :

• {agent-name}

• {tfs-name}

Par exemple, vous avez configuré un agent (comme indiqué dans l’exemple précédent) avec le nom our-osx-agent. Dans les exemples suivants, {tfs-name} est l’un des éléments suivants :

• Azure Pipelines : nom de votre organisation. Par exemple, si vous vous connectez à https://dev.azure.com/fabrikam, le nom du service serait vsts.agent.fabrikam.our-osx-agent

• TFS : nom de votre serveur TFS AT local. Par exemple, si vous vous connectez à http://our-server:8080/tfs, le nom du service serait vsts.agent.our-server.our-osx-agent

Commandes

Passer au répertoire de l’agent

Par exemple, si vous l’avez installé dans le sous-dossier myagent de votre répertoire de base :

cd ~/myagent$

Installer

Commande :

./svc.sh install

Cette commande crée un plist launchd qui pointe vers ./runsvc.sh. Ce script configure l’environnement (plus de détails dans la section suivante) et démarre l’hôte de l’agent.

Démarrer

Commande :

./svc.sh start

Sortie :

starting vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

Le nombre de gauche est le pid si le service est en cours d’exécution. Si le deuxième nombre n’est pas égal à zéro, cela signifie qu’un problème s’est produit.

Statut

Commande :

./svc.sh status

Sortie :

status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

Le nombre de gauche est le pid si le service est en cours d’exécution. Si le deuxième nombre n’est pas égal à zéro, cela signifie qu’un problème s’est produit.

Arrêter

Commande :

./svc.sh stop

Sortie :

stopping vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Stopped

Désinstaller l’interface

Vous devez arrêter avant de désinstaller.

Commande :

./svc.sh uninstall

Connexion et verrouillage automatiques

Normalement, le service d’agent s’exécute uniquement après la connexion de l’utilisateur. Si vous souhaitez que le service d’agent démarre automatiquement lorsque l’ordinateur redémarre, vous pouvez configurer l’ordinateur pour qu’il se connecte et se verrouille automatiquement au démarrage. Consultez Définir votre Mac pour qu’il se connecte automatiquement au démarrage - Support Apple.

Mettre à jour les variables d’environnement

Lorsque vous configurez le service, il prend un instantané de certaines variables d’environnement utiles pour votre utilisateur d’ouverture de session actuel, tel que PATH, LANG, JAVA_HOME, ANT_HOME et MYSQL_PATH. Si vous devez mettre à jour les variables (par exemple, après avoir installé un nouveau logiciel) :

./env.sh
./svc.sh stop
./svc.sh start

L’instantané des variables d’environnement est stocké dans le fichier .env sous le répertoire racine de l’agent. Vous pouvez également modifier ce fichier directement pour appliquer des modifications de variables d’environnement.

Exécuter des instructions avant le démarrage du service

Vous pouvez également exécuter vos propres instructions et commandes pour qu’elles s’exécutent au démarrage du service. Par exemple, vous pouvez configurer l’environnement ou appeler des scripts.

1. Modifier runsvc.sh.

2. Remplacez la ligne suivante par vos instructions :

   # insert anything to setup env when running as a service
   

Fichiers de service

Lorsque vous installez le service, certains fichiers de service sont mis en place.

Fichier de service .plist

Un fichier de service .plist est créé :

~/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

Par exemple :

~/Library/LaunchAgents/vsts.agent.fabrikam.our-osx-agent.plist

./svc.sh install génère ce fichier à partir de ce modèle : ./bin/vsts.agent.plist.template

Fichier .service

./svc.sh start recherche le service en lisant le fichier .service, qui contient le chemin d’accès au fichier de service plist décrit ci-dessus.

Autres mécanismes de service

Nous fournissons le script ./svc.sh comme moyen pratique d’exécuter et de gérer votre agent en tant que service LaunchAgent launchd. Mais vous pouvez utiliser le type de mécanisme de service que vous préférez.

Vous pouvez utiliser le modèle décrit ci-dessus pour faciliter la génération d’autres types de fichiers de service. Par exemple, vous modifiez le modèle pour générer un service qui s’exécute en tant que démon de lancement si vous n’avez pas besoin de tests d’interface utilisateur et que vous ne souhaitez pas configurer la connexion automatique et le verrouillage. Consultez Bibliothèque de développeurs Apple : création de démons et d’agents de lancement.

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 :

1. Arrêtez et désinstallez le service comme expliqué dans la section précédente.

2. Supprimez l’agent.

   ./config.sh remove
   

3. Entrez vos informations d’identification.

Une fois que vous avez 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.

./config.sh --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.sh --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.

Aide sur d’autres options

Pour obtenir des informations sur les autres options :

./config.sh --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é.

Questions fréquentes (FAQ)

Comment vérifier que j’ai 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.

      

   3. Choisissez Pools d’agents.

      

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

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

      

   3. Choisissez Pools d’agents.

      

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

      

   2. Choisissez Pools d’agents.

      

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é.

      

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

      

   3. 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é.

      

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

      

   3. Choisissez l’onglet Fonctionnalités.

      

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

      

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

      

   3. Choisissez l’onglet Fonctionnalités.

      

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.

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.

      

   3. Choisissez Pools d’agents.

      

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

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

      

   3. Choisissez Pools d’agents.

      

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

      

   2. Choisissez Pools d’agents.

      

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é.

      

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

      

   3. 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é.

      

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

      

   3. Choisissez l’onglet Fonctionnalités.

      

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

      

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

      

   3. Choisissez l’onglet Fonctionnalités.

      

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.

Où puis-je en savoir plus sur le fonctionnement du service lancé ?

Bibliothèque de développeurs Apple : création de démons et d’agents de lancement

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

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, suivez les étapes pour arrêter, puis démarrer l’agent.

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

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

Composants requis de TFVC

Si vous utilisez TFVC, vous avez également besoin de Oracle Java JDK 1.6 ou version ultérieure. (Oracle JRE et OpenJDK ne sont pas suffisants à cet effet.)

Le plug-in TEE est utilisé pour les fonctionnalités TFVC. Il dispose d’un CLUF, que vous devez accepter pendant la configuration si vous envisagez d’utiliser TFVC.

Étant donné que le plug-in TEE n’est plus tenu à jour et contient certaines dépendances Java obsolètes, à partir de l’Agent 2.198.0, il n’est plus inclus dans la distribution de l’agent. Toutefois, le plug-in TEE est téléchargé pendant l’exécution de la tâche d’extraction si vous extrayez un référentiel TFVC. Le plug-in TEE est supprimé après l’exécution du travail.

Si l’agent s’exécute derrière un proxy ou un pare-feu, vous devez accepter l’accès au site suivant : https://vstsagenttools.blob.core.windows.net/ Le plug-in TEE est téléchargé à partir de cette adresse.

Si vous utilisez un agent autohébergé et que vous rencontrez des problèmes avec le téléchargement de TEE, vous pouvez installer TEE manuellement :

1. Définissez DISABLE_TEE_PLUGIN_REMOVALl’environnement ou la variable de pipeline sur true. Cette variable empêche l’agent de supprimer le plug-in TEE après l’extraction du référentiel TFVC.
2. Téléchargez manuellement TEE-CLC version 14.135.0 à partir des versions de GitHub Team Explorer Everywhere.
3. Extrayez le contenu du dossier TEE-CLC-14.135.0 vers <agent_directory>/externals/tee.