Agenti macOS autogestiti

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

Per compilare e distribuire app Xcode, è necessario almeno un agente macOS. Questo agente può anche compilare e distribuire app Java e Android.

Informazioni sugli agenti

Se si conosce già cos'è un agente e come funziona, è possibile passare direttamente alle sezioni seguenti. Tuttavia, se desideri ulteriori informazioni su cosa fanno e come funzionano, vedere agenti di Azure Pipelines.

Verificare i prerequisiti

• Sistemi operativi supportati
  • 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 o versione successiva (versione più recente consigliata. È possibile eseguire facilmente l'installazione con Homebrew)

• .NET: il software agente viene eseguito in .NET 6, ma installa la propria versione di .NET in modo che non esista alcun prerequisito .NET.
• TFVC, se stai eseguendo la compilazione da un repository TFVC, vedere i prerequisiti di TFVC .

Preparare le autorizzazioni

Se si esegue la compilazione da un repository Subversion, è necessario installare il client Subversion nel computer.

È consigliabile eseguire manualmente l'installazione dell'agente la prima volta. Dopo aver appreso il funzionamento degli agenti o se si vuole automatizzare la configurazione di molti agenti, è consigliabile usare configurazione automatica.

Sicurezza delle informazioni per gli agenti ospitati internamente

L'utente che configura l'agente ha bisogno delle autorizzazioni di amministratore del pool, ma l'utente che esegue l'agente non ne ha bisogno.

Le cartelle controllate dall'agente devono essere limitate al minor numero possibile di utenti perché contengono segreti che potrebbero essere decrittografati o esfiltrati.

L'agente di Azure Pipelines è un prodotto software progettato per eseguire il codice scaricato da origini esterne. È intrinsecamente un obiettivo per gli attacchi di esecuzione di codice remota (RCE).

È quindi importante considerare il modello di minaccia che circonda ogni singolo utilizzo degli agenti pipeline per eseguire il lavoro e decidere quali sono le autorizzazioni minime che possono essere concesse all'utente che esegue l'agente, al computer in cui viene eseguito l'agente, agli utenti che dispongono dell'accesso in scrittura alla definizione della pipeline, ai repository Git in cui è archiviato il yaml, o il gruppo di utenti che controllano l'accesso al pool per le nuove pipeline.

È consigliabile che l'identità che esegue l'agente sia diversa dall'identità con le autorizzazioni per connettere l'agente al pool. L'utente che genera le credenziali (e altri file correlati all'agente) è diverso dall'utente che deve leggerli. Pertanto, è più sicuro considerare attentamente l'accesso concesso al computer agente stesso e alle cartelle dell'agente che contengono file sensibili, come ad esempio i log e gli elementi.

È opportuno concedere l'accesso alla cartella dell'agente solo agli amministratori DevOps e all'identità utente che esegue il processo dell'agente. Gli amministratori potrebbero dover esaminare il file system per comprendere gli errori di compilazione o ottenere i file di log per poter segnalare gli errori di Azure DevOps.

Decidi quale utente utilizzerai

Come passaggio una tantum, è necessario registrare l'agente. Un utente con l'autorizzazione per amministrare la coda dell'agente deve completare questi passaggi. L'agente non userà le credenziali di questa persona nel funzionamento quotidiano, ma è necessario completare la registrazione. Maggiori informazioni su come comunicano gli agenti.

Verificare che l'utente disponga dell'autorizzazione

Assicurarsi che l'account utente che si intende usare abbia l'autorizzazione per registrare l'agente.

L'utente è proprietario dell'organizzazione di Azure DevOps o TFS o amministratore di Azure DevOps Server? Fermati qui, si dispone dell'autorizzazione.

Altrimenti:

1. Aprire un browser e passare alla scheda pool di agenti per l'organizzazione di Azure Pipelines o il server Azure DevOps Server o TFS:

   1. Accedi alla tua organizzazione (https://dev.azure.com/{yourorganization}).

   2. Scegliere Azure DevOpsImpostazioni dell'organizzazione.

      

   3. Scegliere pool di agenti .

      

   1. Accedi alla raccolta di progetti (http://your-server/DefaultCollection).

   2. Scegliere Azure DevOps, Impostazioni della raccolta.

      

   3. Scegliere pool di agenti .

      

   1. Scegliere Azure DevOps, Impostazioni della raccolta.

      

   2. Scegliere pool di agenti .

      

2. Selezionare il pool sul lato destro della pagina e quindi fare clic su Sicurezza.

3. Se l'account utente che si intende usare non viene visualizzato, contatta un amministratore per farlo aggiungere. L'amministratore può essere un amministratore del pool di agenti, un proprietario dell'organizzazione Azure DevOps , o un amministratore di TFS o Azure DevOps Server .

   Se si tratta di un gruppo di distribuzione agente, l'amministratore può essere un amministratore del gruppo di distribuzione, un proprietario dell'organizzazione di Azure DevOpso un amministratore TFS o Azure DevOps Server.

   È possibile aggiungere un utente al ruolo di amministratore del gruppo di distribuzione nella scheda sicurezza nella pagina gruppi di distribuzione in Azure Pipelines.

Scaricare e configurare l'agente

URL del server

Tipo di autenticazione

Quando si registra un agente, scegliere tra i tipi di autenticazione seguenti e l'installazione dell'agente richiede le informazioni aggiuntive specifiche necessarie per ogni tipo di autenticazione. Per altre informazioni, vedere opzioni di autenticazione dell'agente self-hosted.

Eseguire in modo interattivo

Per indicazioni su se eseguire l'agente in modalità interattiva o come servizio, vedere Agents: Interactive vs. service.

Per eseguire l'agente in modo interattivo:

1. Se hai eseguito l'agente come servizio, disinstalla il servizio.

2. Esegui l'agente.

   ./run.sh
   

Per riavviare l'agente, premere CTRL+C e quindi eseguire run.sh per riavviarlo.

Per usare l'agente, eseguire un processo usando il pool dell'agente. Se non hai scelto un pool diverso, l'agente viene inserito nel pool predefinito .

Esegui una volta

Per gli agenti configurati per l'esecuzione interattiva, è possibile scegliere di fare sì che l'agente accetti un solo incarico. Per l'esecuzione in questa configurazione:

./run.sh --once

Gli agenti in questa modalità accettano un solo lavoro e quindi si arrestano in modo elegante (particolarmente utile per l'esecuzione su un servizio come Azure Container Instances).

Esecuzione come servizio avviato

Forniamo lo script ./svc.sh per l'esecuzione e la gestione del tuo agente come servizio LaunchAgent launchd. Questo script viene generato dopo la configurazione dell'agente. Il servizio ha accesso all'interfaccia utente per eseguire i test dell'interfaccia utente.

Token

Nella sezione seguente questi token vengono sostituiti:

• {agent-name}

• {tfs-name}

Ad esempio, è stato configurato un agente (come illustrato nell'esempio precedente) con il nome our-osx-agent. Negli esempi seguenti, {tfs-name} è una delle seguenti opzioni:

• Azure Pipelines: il nome dell'organizzazione. Ad esempio, se ci si connette a https://dev.azure.com/fabrikam, il nome del servizio sarà vsts.agent.fabrikam.our-osx-agent

• TFS: nome del server TFS AT locale. Ad esempio, se ci si connette a http://our-server:8080/tfs, il nome del servizio sarà vsts.agent.our-server.our-osx-agent

Comandi

Passare alla directory dell'agente

Ad esempio, se è stato installato nella sottocartella myagent della cartella home:

cd ~/myagent$

Installare

Comando:

./svc.sh install

Questo comando crea un launchd plist che punta a ./runsvc.sh. Questo script configura l'ambiente (altri dettagli nella sezione seguente) e avvia l'host dell'agente.

Inizio

Comando:

./svc.sh start

Prodotto:

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}

Il numero a sinistra è il pid se il servizio è in esecuzione. Se il secondo numero non è zero, si è verificato un problema.

Stato

Comando:

./svc.sh status

Prodotto:

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}

Il numero a sinistra è il PID se il servizio è in esecuzione. Se il secondo numero non è zero, si è verificato un problema.

Fermarsi

Comando:

./svc.sh stop

Prodotto:

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

Disinstallare

Dovresti fermarti prima di disinstallare.

Comando:

./svc.sh uninstall

Accesso e blocco automatici

In genere, il servizio agente viene eseguito solo dopo l'accesso dell'utente. Se si desidera che il servizio agente si avvii automaticamente al riavvio del computer, è possibile configurare il computer per l'accesso automatico e bloccarlo all'avvio. Vedi Imposta il Mac per l'accesso automatico durante l'avvio - Supporto Apple.

Aggiornare le variabili di ambiente

Quando si configura il servizio, viene creato uno snapshot di alcune variabili di ambiente utili per l'utente di accesso corrente, ad esempio PATH, LANG, JAVA_HOME, ANT_HOME e MYSQL_PATH. Se è necessario aggiornare le variabili, ad esempio dopo l'installazione di un nuovo software:

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

L'istantanea delle variabili di ambiente viene archiviata nel file .env nella directory radice dell'agente; è anche possibile alterare il file direttamente per applicare le modifiche alle variabili di ambiente.

Eseguire le istruzioni prima dell'avvio del servizio

È anche possibile eseguire istruzioni e comandi personalizzati da eseguire all'avvio del servizio. Ad esempio, è possibile configurare l'ambiente o chiamare script.

1. Modifica runsvc.sh.

2. Sostituire la riga seguente con le istruzioni:

   # insert anything to setup env when running as a service
   

File di servizio

Quando si installa il servizio, vengono inseriti alcuni file di servizio.

File di servizio .plist

Viene creato un file di servizio con estensione .plist:

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

Per esempio:

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

./svc.sh install genera questo file da questo modello: ./bin/vsts.agent.plist.template

File .service

./svc.sh start trova il servizio leggendo il file .service, che contiene il percorso del file del servizio plist descritto in precedenza.

Meccanismi di servizio alternativi

Forniamo lo script ./svc.sh come modo pratico per gestire ed eseguire l'agente come un servizio LaunchAgent launchd. Ma è possibile usare qualsiasi tipo di meccanismo di servizio preferito.

È possibile usare il modello descritto in precedenza per facilitare la generazione di altri tipi di file di servizio. Ad esempio, si modifica il modello per generare un servizio in esecuzione come daemon di avvio se non sono necessari test dell'interfaccia utente e non si vuole configurare l'accesso e il blocco automatici. Consultare Apple Developer Library: Creazione di daemon e agenti di avvio.

Sostituire un agente

Per sostituire un agente, seguire i passaggi Scaricare e configurare nuovamente l'agente.

Quando si configura un agente con lo stesso nome di un agente già esistente, viene chiesto se si vuole sostituire l'agente esistente. Se rispondi Y, assicurati di rimuovere l'agente (vedere di seguito) che stai sostituendo. In caso contrario, dopo alcuni minuti di conflitti, uno degli agenti verrà disattivato.

Rimuovere e riconfigurare un agente

Per rimuovere l'agente:

1. Arrestare e disinstallare il servizio come illustrato nella sezione precedente.

2. Rimuovere l'agente.

   ./config.sh remove
   

3. Immettere le credenziali.

Dopo aver rimosso l'agente, è possibile configurarlo di nuovo.

Configurazione non presidiata

L'agente può essere configurato da uno script senza alcun intervento umano. È necessario inviare --unattended e le risposte a tutte le domande.

./config.sh --help elenca sempre le risposte obbligatorie e facoltative più recenti.

Diagnostica

Se si verificano problemi con l'agente self-hosted, è possibile provare a eseguire la diagnostica. Dopo aver configurato l'agente:

./run.sh --diagnostics

Questa operazione verrà eseguita tramite una suite di diagnostica che può aiutare a risolvere il problema. La funzionalità di diagnostica è disponibile a partire dalla versione dell'agente 2.165.0.

Guida su altre opzioni

Per altre informazioni sulle altre opzioni:

./config.sh --help

L'aiuto fornisce informazioni sulle alternative di autenticazione e sulla configurazione senza supervisione.

Funzionalità

Le funzionalità dell'agente vengono catalogate e pubblicizzate nel pool, in modo che gli vengano assegnate solo le compilazioni e versioni che è in grado di gestire. Vedere Funzionalità dell'agente di compilazione e rilascio.

In molti casi, dopo aver distribuito un agente, sarà necessario installare software o utilità. In genere è consigliabile installare sugli agenti qualsiasi software e strumenti usati nel computer di sviluppo.

Ad esempio, se la compilazione include l'attività npm, la compilazione non verrà eseguita a meno che non sia installato un agente di compilazione nel pool in cui è installato npm.

Domande frequenti

Come posso assicurarmi di avere la versione più recente dell'agente?

1. Passare alla scheda i Pool di agenti:

   1. Accedi alla tua organizzazione (https://dev.azure.com/{yourorganization}).

   2. Scegliere Azure DevOps, Impostazioni dell'organizzazione .

      

   3. Scegliere pool di agenti .

      

   1. Accedi alla raccolta di progetti (http://your-server/DefaultCollection).

   2. Scegliere Azure DevOps, Impostazioni raccolta.

      

   3. Scegliere pool di agenti .

      

   1. Scegliere Azure DevOps, Impostazioni della raccolta.

      

   2. Scegliere pool di agenti .

      

2. Selezionare il pool che contiene l'agente.

3. Assicurarsi che l'agente sia abilitato.

4. Passare alla scheda funzionalità:

   1. Nella scheda pool di agenti, selezionare il pool di agenti desiderato.

      

   2. Seleziona Agenti e scegli l'agente desiderato.

      

   3. Scegliere la scheda Funzionalità.

      

      Nota

      Gli agenti ospitati da Microsoft non visualizzano le funzionalità di sistema. Per un elenco del software installato in agenti ospitati da Microsoft, vedere Usare un agente ospitato da Microsoft.

   1. Nella scheda pool di agenti , selezionare il pool desiderato.

      

   2. Selezionare Agenti e scegliere l'agente desiderato.

      

   3. Scegliere la scheda Funzionalità.

      

   1. Nella scheda pool di agenti, selezionare il pool desiderato.

      

   2. Selezionare Agenti e scegliere l'agente desiderato.

      

   3. Scegliere la scheda Funzionalità.

      

5. Cerca la funzionalità del Agent.Version. È possibile controllare questo valore rispetto alla versione dell'agente più recente pubblicata. Vedete Azure Pipelines Agent e controllate la pagina per il numero di versione più alto elencato.

6. Ogni agente si aggiorna automaticamente quando esegue un'attività che richiede una versione più recente dell'agente. Per aggiornare manualmente alcuni agenti, fare clic con il pulsante destro del mouse sul pool e selezionare Aggiornare tutti gli agenti.

Come posso assicurarmi di avere la versione più recente dell'agente?

1. Passare alla scheda pool di agenti

   1. Accedere alla tua organizzazione (https://dev.azure.com/{yourorganization}).

   2. Scegliere Azure DevOps, Impostazioni dell'organizzazione.

      

   3. Scegliere pool di agenti .

      

   1. Effettua l'accesso alla raccolta di progetti (http://your-server/DefaultCollection).

   2. Scegliere Azure DevOps, Impostazioni della raccolta.

      

   3. Scegliere pool di agenti .

      

   1. Scegliere Azure DevOps, Impostazioni della raccolta.

      

   2. Scegliere pool di agenti .

      

2. Fare clic sul pool che contiene l'agente.

3. Assicurarsi che l'agente sia abilitato.

4. Passare alla scheda funzionalità:

   1. Nella scheda pool di agenti , selezionare il pool di agenti desiderato.

      

   2. Selezionare Agenti e scegliere l'agente desiderato.

      

   3. Scegliere la scheda Funzionalità.

      

      Nota

      Gli agenti ospitati da Microsoft non visualizzano le funzionalità di sistema. Per un elenco del software installato in agenti ospitati da Microsoft, vedere Usare un agente ospitato da Microsoft.

   1. Nella scheda pool di agenti, selezionare il pool desiderato.

      

   2. Selezionare Agenti e scegliere l'agente desiderato.

      

   3. Scegliere la scheda Funzionalità.

      

   1. Nella scheda pool di agenti, selezionare il pool desiderato.

      

   2. Seleziona Agenti e scegli l'agente desiderato.

      

   3. Scegliere la scheda Funzionalità.

      

5. Cerca la funzionalità Agent.Version. È possibile controllare questo valore rispetto alla versione dell'agente pubblicata più recente. Consulta Azure Pipelines Agent e controlla la pagina per il numero di versione più alto elencato.

6. Ogni agente si aggiorna automaticamente quando esegue un'attività che richiede una versione più recente dell'agente. Per aggiornare manualmente alcuni agenti, fare clic con il pulsante destro del mouse sul pool e selezionare Aggiornare tutti gli agenti.

Dove è possibile ottenere altre informazioni sul funzionamento del servizio avviato?

Apple Developer Library: Creazione di daemon e agenti di avvio

Come si esegue l'agente con un certificato autofirmato?

Eseguire l'agente con un certificato autofirmato

Come si esegue l'agente dietro un proxy web?

Eseguire l'agente dietro un proxy web

Come faccio a riavviare l'agente

Se si sta eseguendo l'agente in modo interattivo, vedere le istruzioni di riavvio in Eseguire in modo Interattivo. Se si esegue l'agente come servizio, seguire la procedura per Arrestare quindi Avviare l'agente.

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

Prerequisiti di Team Foundation Version Control

Se utilizzerai TFVC, avrai anche bisogno di Oracle Java JDK 1.6 o di una versione successiva. A questo scopo, Oracle JRE e OpenJDK non sono sufficienti.

TEE plug-in viene usato per la funzionalità TFVC. Ha un contratto di licenza, che è necessario accettare durante la configurazione se si prevede di usare TFVC.

Poiché il plug-in TEE non è più gestito e contiene alcune dipendenze Java non aggiornate, a partire da Agent 2.198.0 non è più incluso nella distribuzione dell'agente. Tuttavia, il plug-in TEE viene scaricato durante l'esecuzione dell'attività di estrazione se si sta effettuando il checkout di un repository TFVC. Il plug-in TEE viene rimosso dopo l'esecuzione del processo.

Se l'agente è in esecuzione dietro un proxy o un firewall, è necessario accettare per garantire l'accesso al sito seguente: https://vstsagenttools.blob.core.windows.net/. Il plug-in TEE viene scaricato da questo indirizzo.

Se si usa un agente self-hosted e si riscontrano problemi con il download di TEE, è possibile installare TEE manualmente:

1. Impostare la variabile di ambiente DISABLE_TEE_PLUGIN_REMOVAL o la variabile pipeline su true. Questa variabile impedisce all'agente di rimuovere il plug-in TEE dopo il checkout del repository TFVC.
2. Scaricare manualmente TEE-CLC versione 14.135.0 da Versioni di GitHub di Team Explorer ovunque.
3. Estrarre il contenuto della cartella TEE-CLC-14.135.0 in <agent_directory>/externals/tee.