Agentes do macOS auto-hospedados

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

Para criar e implantar aplicativos Xcode ou projetos Xamarin.iOS, você precisa de pelo menos um agente macOS. Esse agente também podem compilar e implantar aplicativos Java e Android.

Saiba mais sobre agentes

Se você já sabe o que é um agente e como ele funciona, fique à vontade para ir direto para as seções a seguir. Mas se você quiser saber mais sobre o que eles fazem e como eles funcionam, confira Agentes do Azure Pipelines.

Verificar pré-requisitos

• Sistemas operacionais com suporte
  • 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 superior (versão mais recente recomendada – você pode instalar facilmente com o Homebrew)

• .NET – O software do agente é executado no .NET 6, mas instala sua própria versão do .NET para que não haja pré-requisitos do .NET.
• TFVC – Se você estiver criando a partir de um repositório TFVC, confira Pré-requisitos do TFVC.

Preparar permissões

Se você estiver criando a partir de um repositório Subversion, precisará instalar o cliente Subversion no computador.

Você deve executar a configuração do agente manualmente na primeira vez. Depois de ter uma ideia de como os agentes funcionam ou se você quiser automatizar a configuração de muitos agentes, considere usar a configuração autônoma.

Segurança da informação para agentes auto-hospedados

O usuário que configura o agente precisa de permissões de administrador do pool, mas o usuário que executa o agente não.

As pastas controladas pelo agente devem ser restritas ao menor número possível de usuários, pois contêm segredos que poderão ser descriptografados ou exfiltrados.

O agente do Azure Pipelines é um produto de software projetado para executar código baixado de fontes externas. Ele inerentemente pode ser um alvo de ataques de RCE (execução remota de código).

Portanto, é importante considerar o modelo de ameaça que envolve cada uso individual de Agentes de Pipelines para executar o trabalho e decidir quais são as permissões mínimas que podem ser concedidas ao usuário que executa o agente, à máquina em que o agente é executado, aos usuários que têm acesso de gravação à definição de Pipeline, aos repositórios git em que o yaml está armazenado ou o grupo de usuários que controlam o acesso ao pool para novos pipelines.

É uma prática recomendada fazer com que a identidade que executa o agente seja diferente da identidade que tem permissões para conectar o agente ao pool. O usuário que gera as credenciais (e outros arquivos relacionados ao agente) é diferente do usuário que precisa lê-las. Portanto, é mais seguro considerar cuidadosamente o acesso permitido ao computador do agente propriamente dito, e às pastas de agente que contêm arquivos confidenciais, como logs e artefatos.

Faz sentido permitir acesso à pasta do agente somente para administradores de DevOps e a identidade do usuário que executa o processo do agente. Os administradores podem precisar investigar o sistema de arquivos para entender falhas de build ou obter arquivos de log para poder relatar falhas do Azure DevOps.

Decidir qual usuário você usará

Como uma etapa a ser realizada apenas uma vez, você precisa registrar o agente. Alguém com permissão para administrar a fila de agentes precisa concluir essas etapas. O agente não usará as credenciais dessa pessoa na operação diária, mas elas são necessárias para conclusão do registro. Saiba mais sobre como os agentes se comunicam.

Confirmar se o usuário tem permissão

Verifique se a conta de usuário que você vai usar tem permissão para registrar o agente.

O usuário é um proprietário da organização do Azure DevOps ou administrador do Azure DevOps Server ou TFS? Pare aqui, você tem a permissão necessária.

Caso contrário:

1. Abra um navegador e navegue até a guia Pools de agentes para sua organização do Azure Pipelines ou Azure DevOps Server ou servidor TFS:

   1. Entre em sua organização (https://dev.azure.com/{yourorganization}).

   2. Escolha Azure DevOps, Configurações da organização.

      

   3. Escolha Pools de agentes.

      

   1. Entre na sua coleção de projetos (http://your-server/DefaultCollection).

   2. Escolha Azure DevOps, Configurações de coleção.

      

   3. Escolha Pools de agentes.

      

   1. Escolha Azure DevOps, Configurações de coleção.

      

   2. Escolha Pools de agentes.

      

2. Selecione o pool no lado direito da página e clique em Segurança.

3. Se a conta de usuário que você vai usar não for mostrada, solicite a um administrador que a adicione. O administrador pode ser um administrador do pool de agentes, um proprietário da organização do Azure DevOps ou um administrador do TFS ou Azure DevOps Server.

   Se esse se tratar de um agente de grupo de implantação, o administrador poderá ser um administrador de grupo de implantação, um proprietário da organização do Azure DevOps ou um administrador do TFS ou Azure DevOps Server.

   Você pode adicionar um usuário à função de administrador do grupo de implantação na guia Segurança, na página Grupos de Implantação no Azure Pipelines.

Baixar e configurar o agente

Servidor URL

Tipo de autenticação

Ao registrar um agente, escolha entre os tipos de autenticação a seguir e a configuração do agente solicitará as informações adicionais específicas necessárias para cada tipo de autenticação. Para obter mais informações, consulte Opções de autenticação de agente auto-hospedado.

Executar de maneira interativa

Para obter diretrizes sobre se o agente deve ser executado no modo interativo ou como um serviço, confira Agentes: interativo vs. de serviço.

Para executar o agente de maneira interativa:

1. Se você estiver executando o agente como um serviço, desinstale o serviço.

2. Execute o agente.

   ./run.sh
   

Para reiniciar o agente, pressione Ctrl+C e execute run.sh para reiniciá-lo.

Para usar seu agente, execute um trabalho usando o pool do agente. Se você não escolheu um pool diferente, seu agente é colocado no pool Padrão.

Executar uma vez

Para agentes configurados para serem executados interativamente, você pode optar por fazer com que o agente aceite apenas um trabalho. Para executar nessa configuração:

./run.sh --once

Os agentes nesse modo aceitam apenas um trabalho e, em seguida, giram normalmente (útil para execução em um serviço como as Instâncias de Contêiner do Azure).

Executar como serviço launchd

Fornecemos o script ./svc.sh para você executar e gerenciar seu agente como um serviço launchd LaunchAgent. Esse script será gerado depois que você configurar o agente. O serviço tem acesso à interface do usuário para executar seus testes de interface do usuário.

Tokens

Na seção a seguir, esses tokens serão substituídos:

• {agent-name}

• {tfs-name}

Por exemplo, você configurou um agente (como mostrado no exemplo anterior) com o nome our-osx-agent. Nos exemplos a seguir, {tfs-name} será:

• Azure Pipelines: o nome da sua organização. Por exemplo, se você se conectar a https://dev.azure.com/fabrikam, o nome do serviço será vsts.agent.fabrikam.our-osx-agent

• TFS: o nome do servidor TFS AT local. Por exemplo, se você se conectar a http://our-server:8080/tfs, o nome do serviço será vsts.agent.our-server.our-osx-agent

Comandos

Alterar para o diretório do agente

Por exemplo, se você instalou na subpasta myagent do diretório base:

cd ~/myagent$

Instalar

Comando:

./svc.sh install

Esse comando cria um launchd plist que aponta para ./runsvc.sh. Esse script configura o ambiente (mais detalhes na seção a seguir) e inicia o host dos agentes.

Iniciar

Comando:

./svc.sh start

Saída:

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}

O número esquerdo será o pid se o serviço estiver em execução. Se o segundo número não for zero, ocorreu um problema.

Status

Comando:

./svc.sh status

Saída:

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}

O número esquerdo será o pid se o serviço estiver em execução. Se o segundo número não for zero, ocorreu um problema.

Stop

Comando:

./svc.sh stop

Saída:

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

Desinstalar

Você deve parar antes de desinstalar.

Comando:

./svc.sh uninstall

Logon e bloqueio automáticos

Normalmente, o serviço de agente é executado somente depois que o usuário faz logon. Se você quiser que o serviço do agente seja iniciado automaticamente quando o computador for reiniciado, você poderá configurar o computador para fazer logon e bloquear automaticamente na inicialização. Confira Definir seu Mac para fazer logon automaticamente durante a inicialização – Suporte da Apple.

Atualizar variáveis de ambiente

Quando você configura o serviço, ele usa uma instantâneo de algumas variáveis de ambiente úteis para o usuário de logon atual, como PATH, LANG, JAVA_HOME, ANT_HOME e MYSQL_PATH. Se você precisar atualizar as variáveis (por exemplo, depois de instalar algum novo software):

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

O instantâneo das variáveis de ambiente é armazenado no arquivo .env no diretório raiz do agente, você também pode alterar o arquivo diretamente para aplicar alterações de variável de ambiente.

Executar instruções antes do serviço ser iniciado

Você também pode executar suas instruções e comandos a serem executados quando o serviço for iniciado. Por exemplo, você pode configurar o ambiente ou chamar scripts.

1. Edite runsvc.sh.

2. Substitua a seguinte linha por suas instruções:

   # insert anything to setup env when running as a service
   

Arquivos do serviço

Quando você instala o serviço, alguns arquivos de serviço são colocados em prática.

Arquivo de serviço .plist

Um arquivo de serviço .plist é criado:

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

Por exemplo:

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

./svc.sh install gera esse arquivo a partir deste modelo: ./bin/vsts.agent.plist.template

Arquivo .service

./svc.sh start localiza o serviço lendo o arquivo .service, que contém o caminho para o arquivo de serviço plist descrito acima.

Mecanismos de serviço alternativos

Fornecemos o script ./svc.sh como uma maneira conveniente de executar e gerenciar seu agente como um serviço launchd LaunchAgent. Mas você pode usar qualquer tipo de mecanismo de serviço que preferir.

Você pode usar o modelo descrito acima como para facilitar a geração de outros tipos de arquivo de serviço. Por exemplo, você modificará o modelo para gerar um serviço executado como daemon de inicialização, se você não precisar de testes de interface do usuário e não quiser configurar o logon automático e bloquear. Confira Biblioteca de Desenvolvedores da Apple: como criar daemons e agentes de inicialização.

Substituir um agente

Para substituir um agente, siga novamente as etapas de Baixar e configurar o agente.

Ao configurar um agente usando o mesmo nome de um agente que já existe, você será perguntado se deseja substituir o agente existente. Se você responder Y, remova o agente (veja abaixo) que você está substituindo. Caso contrário, após alguns minutos de conflitos, um dos agentes será desligado.

Remover e reconfigurar um agente

Para remover o agente:

1. Pare e desinstale o serviço, conforme explicado na seção anterior.

2. Remova o agente.

   ./config.sh remove
   

3. Insira suas credenciais.

Depois de remover o agente, você pode configurá-lo novamente.

Configuração autônoma

O agente pode ser configurado a partir de um script, sem intervenção humana. Você deve passar --unattended e as respostas para todas as perguntas.

./config.sh --help sempre lista as respostas obrigatórias e opcionais mais recentes.

Diagnósticos

Se você estiver tendo problemas com seu agente auto-hospedado, tente executar o diagnóstico. Depois de configurar o agente:

./run.sh --diagnostics

Isso será executado por meio de um pacote de diagnóstico que pode ajudar você a solucionar o problema. O recurso diagnóstico está disponível a partir da versão 2.165.0 do agente.

Ajuda em outras opções

Para saber mais sobre outras opções:

./config.sh --help

A ajuda fornece informações sobre alternativas de autenticação e configuração autônoma.

Funcionalidades

Os recursos do agente são catalogados e anunciados no pool para que apenas os builds e lançamentos que ele possa manipular sejam atribuídos a ele. Confira Funcionalidades do agente de build e lançamento.

Em muitos casos, depois de implantar um agente, você precisará instalar software ou utilitários. Em geral, você deve instalar em seus agentes qualquer software e ferramentas usados em seu computador de desenvolvimento.

Por exemplo, se o build incluir a tarefa npm, o build não será executado, a menos que haja um agente de build no pool que tenha o npm instalado.

Perguntas frequentes

Como fazer ter certeza de que tenho a versão mais recente do agente?

1. Navegue até a guia Pools de agentes:

   1. Entre em sua organização (https://dev.azure.com/{yourorganization}).

   2. Escolha Azure DevOps, Configurações da organização.

      

   3. Escolha Pools de agentes.

      

   1. Entre na sua coleção de projetos (http://your-server/DefaultCollection).

   2. Escolha Azure DevOps, Configurações de coleção.

      

   3. Escolha Pools de agentes.

      

   1. Escolha Azure DevOps, Configurações de coleção.

      

   2. Escolha Pools de agentes.

      

2. Clique no pool que contém o agente.

3. Verifique se o agente está habilitado.

4. Navegue até a guia Funcionalidades:

   1. Na guia Pools de agentes, selecione o pool de agentes desejado.

      

   2. Selecione Agentes e escolha o agente desejado.

      

   3. Selecione a guia Funcionalidades.

      

      Observação

      Os agentes hospedados pela Microsoft não exibem funcionalidades do sistema. Para obter uma lista de softwares instalados em agentes hospedados pela Microsoft, confira Usar um agente hospedado pela Microsoft.

   1. Na guia Pools de agentes, selecione o pool desejado.

      

   2. Selecione Agentes e escolha o agente desejado.

      

   3. Selecione a guia Funcionalidades.

      

   1. Na guia Pools de agentes, selecione o pool desejado.

      

   2. Selecione Agentes e escolha o agente desejado.

      

   3. Selecione a guia Funcionalidades.

      

5. Procure a funcionalidade Agent.Version. Você pode verificar esse valor em relação à versão publicada mais recente do agente. Confira Agente do Azure Pipelines e confira a página para ver o número de versão mais alto listado.

6. Cada agente é atualizado automaticamente quando executa uma tarefa que exige uma versão mais recente do agente. Se você quiser atualizar manualmente alguns agentes, clique com o botão direito do mouse no pool e selecione Atualizar todos os agentes.

Como fazer ter certeza de que tenho a versão mais recente do agente?

1. Navegue até a guia Pools de agentes:

   1. Entre em sua organização (https://dev.azure.com/{yourorganization}).

   2. Escolha Azure DevOps, Configurações da organização.

      

   3. Escolha Pools de agentes.

      

   1. Entre na sua coleção de projetos (http://your-server/DefaultCollection).

   2. Escolha Azure DevOps, Configurações de coleção.

      

   3. Escolha Pools de agentes.

      

   1. Escolha Azure DevOps, Configurações de coleção.

      

   2. Escolha Pools de agentes.

      

2. Clique no pool que contém o agente.

3. Verifique se o agente está habilitado.

4. Navegue até a guia Funcionalidades:

   1. Na guia Pools de agentes, selecione o pool de agentes desejado.

      

   2. Selecione Agentes e escolha o agente desejado.

      

   3. Selecione a guia Funcionalidades.

      

      Observação

      Os agentes hospedados pela Microsoft não exibem funcionalidades do sistema. Para obter uma lista de softwares instalados em agentes hospedados pela Microsoft, confira Usar um agente hospedado pela Microsoft.

   1. Na guia Pools de agentes, selecione o pool desejado.

      

   2. Selecione Agentes e escolha o agente desejado.

      

   3. Selecione a guia Funcionalidades.

      

   1. Na guia Pools de agentes, selecione o pool desejado.

      

   2. Selecione Agentes e escolha o agente desejado.

      

   3. Selecione a guia Funcionalidades.

      

5. Procure a funcionalidade Agent.Version. Você pode verificar esse valor em relação à versão publicada mais recente do agente. Confira Agente do Azure Pipelines e confira a página para ver o número de versão mais alto listado.

6. Cada agente é atualizado automaticamente quando executa uma tarefa que exige uma versão mais recente do agente. Se você quiser atualizar manualmente alguns agentes, clique com o botão direito do mouse no pool e selecione Atualizar todos os agentes.

Onde posso saber mais sobre como o serviço launchd funciona?

Biblioteca de Desenvolvedores da Apple: como criar daemons e agentes de inicialização

Como fazer para executar o agente com um certificado autoassinado?

Executar o agente com um certificado autoassinado

Como fazer para executar o agente por trás de um proxy Web?

Executar o agente por trás de um proxy Web

Como reiniciar o agente

Se você estiver executando o agente interativamente, consulte as instruções de reinicialização em Executar interativamente. Se você estiver executando o agente como um serviço, siga as etapas para Parar e Iniciar o 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

Pré-requisitos do TFVC

Se você usar o TFVC, também precisará do Oracle Java JDK 1.6 ou superior. (O Oracle JRE e o OpenJDK não são suficientes para essa finalidade.)

O plug-in TEE é usado para a funcionalidade do TFVC. Ele tem um EULA, que você deve aceitar durante a configuração se planeja trabalhar com o TFVC.

Como o plug-in TEE não é mais mantido e contém algumas dependências Java desatualizadas, o agente 2.198.0 e versões posteriores não estão mais incluídos na distribuição do agente. No entanto, o plug-in TEE será baixado durante a execução da tarefa de check-out se você estiver fazendo check-out de um repositório TFVC. O plug-in TEE é removido após a execução do trabalho.

Se o agente estiver em execução atrás de um proxy ou firewall, você deverá aceitar garantir o acesso ao seguinte site: https://vstsagenttools.blob.core.windows.net/. O plug-in TEE é baixado desse endereço.

Se você estiver usando um agente auto-hospedado e enfrentando problemas com o download do TEE, poderá instalar o TEE manualmente:

1. Defina a variável de pipeline ou ambiente DISABLE_TEE_PLUGIN_REMOVAL como true. Essa variável impede que o agente remova o plug-in TEE após a verificação do repositório TFVC.
2. Baixe o TEE-CLC versão 14.135.0 manualmente de Versões do GitHub do Team Explorer Everywhere.
3. Extraia o conteúdo da pasta TEE-CLC-14.135.0 para <agent_directory>/externals/tee.