Локальные агенты macOS

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

Чтобы создавать и развертывать приложения Xcode, вам потребуется по крайней мере один агент macOS. Этот агент также может создавать и развертывать приложения Java и Android.

Сведения об агентах

Если вы уже знаете, какой агент и как он работает, вы можете перейти прямо к следующим разделам. Но если вы хотите узнать больше о том, что они делают и как работают, см. агенты Azure Pipelines.

Проверка предварительных условий

• Поддерживаемые операционные системы
  • x64
    • macOS 10.15 "Catalina"
    • macOS 11.0 "Big Sur"
    • macOS 12.0 "Монтерей"
    • macOS 13.0 "Ventura"
    • macOS 14.0 "Сонома"
  • ARM64
    • macOS 11.0 "Big Sur"
    • macOS 12.0 "Монтерей"
    • macOS 13.0 "Ventura"
    • macOS 14.0 "Сонома"

• Git — Git 2.9.0 или более поздней (рекомендуется последняя версия — вы можете легко установить с помощью Homebrew)

• .NET — программное обеспечение агента выполняется в .NET 6, но устанавливает собственную версию .NET, поэтому не существует необходимых условий для .NET.
• TFVC. Если вы собираете проект из репозитория TFVC, см. предварительные требования TFVC.

Подготовка разрешений

Если вы собираете проект из репозитория Subversion, необходимо установить клиент Subversion на машине.

При первом запуске программы установки агента необходимо выполнить настройку агента вручную. После получения сведений о том, как работают агенты или вы хотите автоматизировать настройку множества агентов, рассмотрите возможность использования автоматической настройки конфигурации.

Информационная безопасность для локальных агентов

Пользователю, настраивающему агента, требуются разрешения администратора пула, но пользователю, запускающему агента, они не нужны.

Папки, контролируемые агентом, должны быть доступны как можно меньшему числу пользователей, так как они содержат секреты, которые могут быть расшифрованы или эксфильтрованы.

Агент Azure Pipelines — это программный продукт, предназначенный для выполнения кода, скачиваемого из внешних источников. По сути это может быть мишенью для атак удаленного выполнения кода (RCE).

Поэтому важно рассмотреть модель угроз, связанную с каждым отдельным использованием агентов Конвейеров для выполнения работы, и решить, какие минимальные разрешения могут быть предоставлены пользователю, на котором работает агент, пользователям, у которых есть доступ на запись к определению конвейера, репозитории git, в которых хранится yaml, или группа пользователей, которые управляют доступом к пулу для новых конвейеров.

Рекомендуется, чтобы идентифицирующая информация для выполнения агента отличалась от той, что имеет разрешения на подключение агента к пулу. Пользователь, создающий учетные данные (и другие файлы, связанные с агентом), отличается от пользователя, который должен читать их. Поэтому рекомендуется тщательно рассмотреть доступ к самому компьютеру агента, а также папки агента, содержащие конфиденциальные файлы, такие как журналы и артефакты.

Имеет смысл предоставить доступ к папке агента только для администраторов DevOps и пользовательской учетной записи, запускающей агентский процесс. Администраторам может потребоваться исследовать файловую систему, чтобы понять ошибки сборки или получить файлы журналов, чтобы сообщить о сбоях Azure DevOps.

Выберите пользователя

Сначала необходимо зарегистрировать агента. Кто-то с разрешением администрировать очередь агента должен выполнить эти действия. Агент не будет использовать учетные данные этого пользователя в повседневной работе, но они необходимы для завершения регистрации. Дополнительные сведения о том, как агенты взаимодействуют.

Убедитесь, что у пользователя есть разрешение

Убедитесь, что учетная запись пользователя, которую вы собираетесь использовать, имеет разрешение на регистрацию агента.

Является ли пользователь владельцем организации Azure DevOps или администратором TFS или Azure DevOps Server? Остановитесь здесь, у вас есть разрешение.

Иначе:

1. Откройте браузер и перейдите на вкладку пулов агентов для организации Azure Pipelines или сервера Azure DevOps Server или TFS:

   1. Войдите в организацию (https://dev.azure.com/{yourorganization}).

   2. Выберите Azure DevOps, параметры организации.

      

   3. Выберите пулы агентов .

      вкладка "Выбор пулов агентов"

   1. Войдите в коллекцию проектов (http://your-server/DefaultCollection).

   2. Выберите Azure DevOps, параметры коллекции.

      

   3. Выберите пулы агентов .

      

   1. Выберите Azure DevOps,, Параметры коллекции.

      

   2. Выберите пулы агентов .

      

2. Выберите пул справа от страницы и щелкните "Безопасность".

3. Если учетная запись пользователя, которую вы собираетесь использовать, не отображается, обратитесь к администратору, чтобы добавить её. Администратор может быть администратором пула агентов, владельцем организации Azure DevOpsили TFS или администратором Azure DevOps Server.

   Если это агент группы развертывания , администратор может быть администратором группы развертывания, владельцем организации Azure DevOpsили TFS или администратором Azure DevOps Server.

   Вы можете добавить пользователя в роль администратора группы развертывания на вкладке Безопасность на странице Группы развертывания в Azure Pipelines.

Скачивание и настройка агента

URL-адрес сервера

Тип проверки подлинности

При регистрации агента выберите один из следующих типов проверки подлинности, а программа установки агента запрашивает дополнительные сведения, необходимые для каждого типа проверки подлинности. Дополнительные сведения см. в разделе параметры проверки подлинности локального агента.

Интерактивное выполнение

Рекомендации по запуску агента в интерактивном режиме или в качестве службы см. в разделе Agent: Interactive vs. Service.

Чтобы запустить агент в интерактивном режиме, выполните следующие действия.

1. Если вы запускали агент как службу, удалите службу.

2. Запустите агент.

   ./run.sh
   

Чтобы перезапустить агент, нажмите клавиши CTRL+C, а затем запустите run.sh, чтобы перезапустить его.

Чтобы использовать своего агента, используйте пул агента для выполнения задания . Если вы не выбрали другой пул, ваш агент помещается в пул по умолчанию .

Выполнить один раз

Для агентов, настроенных для интерактивного запуска, можно выбрать, чтобы агент принял только одно задание. Чтобы выполнить эту конфигурацию, выполните указанные ниже действия.

./run.sh --once

Агенты в этом режиме принимают только одно задание, после чего корректно завершают свою работу (полезно для запуска в службе, такой как Azure Container Instances).

Запуск от имени запущенной службы

Мы предоставляем скрипт ./svc.sh для запуска и управления агентом в качестве службы launchd LaunchAgent. Этот скрипт создается после настройки агента. Служба имеет доступ к пользовательскому интерфейсу для выполнения тестов пользовательского интерфейса.

Маркеры

В следующем разделе эти маркеры заменяются:

• {agent-name}

• {tfs-name}

Например, вы настроили агент (как показано в предыдущем примере) с именем our-osx-agent. В следующих примерах {tfs-name} может быть:

• Azure Pipelines: имя вашей организации. Например, при подключении к https://dev.azure.com/fabrikamимя службы будет vsts.agent.fabrikam.our-osx-agent

• TFS: имя локального сервера TFS AT. Например, при подключении к http://our-server:8080/tfsимя службы будет vsts.agent.our-server.our-osx-agent

Команды

Изменение каталога агента

Например, если вы установили в папке myagent в домашнем каталоге:

cd ~/myagent$

Установить

Команда:

./svc.sh install

Эта команда создает launchd plist, указывающий на ./runsvc.sh. Этот скрипт настраивает среду (дополнительные сведения в следующем разделе) и запускает хост агента.

Начало

Команда:

./svc.sh start

Выпуск:

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}

Левый номер является идентификатором процесса (pid), если служба запущена. Если второй номер не равен нулю, возникла проблема.

Статус

Команда:

./svc.sh status

Выпуск:

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}

Число слева — это pid, если служба запущена. Если второй номер не равен нулю, возникла проблема.

Остановка

Команда:

./svc.sh stop

Выпуск:

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

Удалить

Прекратите, прежде чем удалите.

Команда:

./svc.sh uninstall

Автоматический вход и блокировка

Как правило, служба агента выполняется только после входа пользователя. Если вы хотите, чтобы служба агента автоматически запускалась при перезапуске компьютера, вы можете настроить компьютер для автоматической авторизации и блокировки экрана при запуске. См. как настроить автоматический вход в систему Mac во время запуска — служба поддержки Apple.

Обновление переменных среды

При настройке службы делается моментальный снимок некоторых полезных переменных среды для текущего пользователя, выполняющего вход, например PATH, LANG, JAVA_HOME, ANT_HOME и MYSQL_PATH. Если необходимо обновить переменные (например, после установки нового программного обеспечения):

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

Моментальный снимок переменных среды хранится в файле .env в корневом каталоге агента, вы также можете изменить этот файл непосредственно для применения изменений переменной среды.

Выполнение инструкций перед запуском службы

Вы также можете выполнять собственные инструкции и команды для запуска службы. Например, можно настроить среду или вызвать скрипты.

1. Редактировать runsvc.sh.

2. Замените следующую строку инструкциями:

   # insert anything to setup env when running as a service
   

Файлы службы

При установке службы некоторые файлы служб помещаются.

.plist-файл службы

Создаётся файл службы .plist:

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

Например:

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

./svc.sh install создает этот файл из этого шаблона: ./bin/vsts.agent.plist.template

Файл .service

./svc.sh start находит службу, считывая файл .service, содержащий путь к файлу службы plist, описанному выше.

Альтернативные механизмы обслуживания

Мы предоставляем скрипт ./svc.sh в качестве удобного способа для запуска и управления вашим агентом в виде службы launchd LaunchAgent. Но вы можете использовать любой тип механизма обслуживания, который вы предпочитаете.

Шаблон, описанный выше, можно использовать для упрощения создания других типов файлов службы. Например, вы измените шаблон, чтобы создать службу, которая выполняется в качестве управляющей программы запуска, если вам не нужны тесты пользовательского интерфейса и не хотите настраивать автоматический вход и блокировку. См. библиотеку разработчиков Apple: Создание демонов и агентов.

Замена агента

Чтобы заменить агента, следуйте шагам загрузки и настройки агента еще раз.

При настройке агента с тем же именем, что и существующий, вам будет предложено заменить его. Если вы отвечаете Y, убедитесь, что удаляете агента (см. ниже), которого заменяете. В противном случае после нескольких минут конфликтов один из агентов завершит работу.

Удаление и перенастройка агента

Чтобы удалить агент, выполните следующие действия.

1. Остановите и удалите службу, как описано в предыдущем разделе.

2. Удалите агент.

   ./config.sh remove
   

3. Введите свои учетные данные.

После удаления агента можно снова настроить его.

Настройка без присмотра

Агент можно настроить из скрипта без вмешательства человека. Необходимо передать --unattended и ответы на все вопросы.

./config.sh --help всегда перечисляет последние необходимые и необязательные ответы.

Диагностика

Если у вас возникли проблемы с локальным агентом, попробуйте выполнить диагностику. После настройки агента:

./run.sh --diagnostics

Это приведет к выполнению набора диагностики, который может помочь устранить проблему. Функция диагностики доступна начиная с агента версии 2.165.0.

Справка по другим опциям

Чтобы узнать о других вариантах, выполните следующие действия.

./config.sh --help

Эта справка содержит сведения об альтернативных вариантах проверки подлинности и настройке без участия пользователя.

Возможности

Возможности агента каталогизируются и публикуются в пуле, чтобы ему назначались только те сборки и выпуски, которые он может обрабатывать. См. возможности агента сборки и развёртывания.

Во многих случаях после развертывания агента необходимо установить программное обеспечение или служебные программы. Как правило, следует установить на ваши агенты то программное обеспечение и инструменты, которые вы используете на вашей машине разработки.

Например, если сборка включает npm-задачу , сборка не будет выполняться, если в пуле нет агента сборки с установленным npm.

Вопросы и ответы

Как убедиться, что у меня установлена последняя версия агента?

1. Перейдите на вкладку пулов агентов :

   1. Войдите в организацию (https://dev.azure.com/{yourorganization}).

   2. Выберите Azure DevOps, Параметры организации.

      

   3. Выберите пулы агентов .

      вкладка "Выбор пулов агентов"

   1. Войдите в коллекцию проектов (http://your-server/DefaultCollection).

   2. Выберите Azure DevOps, параметры коллекции.

      

   3. Выберите пулы агентов .

      

   1. Выберите Azure DevOps, параметры коллекции .

      

   2. Выберите пулы агентов .

      

2. Щелкните пул, содержащий агент.

3. Убедитесь, что агент включен.

4. Перейдите на вкладку возможностей:

   1. На вкладке "Пулы агентов" выберите нужный пул агентов.

      

   2. Выберите агентов и выберите нужного агента.

      

   3. Выберите вкладку Возможности.

      

      Заметка

      Размещенные корпорацией Майкрософт агенты не отображают системные возможности. Список программного обеспечения, установленного в агентах, размещенных корпорацией Майкрософт, см. в статье Использование размещенного корпорацией Майкрософт агента.

   1. На вкладке пулы агентов выберите нужный пул.

      

   2. Выберите агент и выберите нужного агента.

      

   3. Перейдите на вкладку Возможности.

      вкладка "Возможности агента

   1. На вкладке пулы агентов выберите нужный пул.

      

   2. Выберите агента и выберите нужного агента.

      

   3. Перейдите на вкладку возможностей.

      

5. Найдите функцию Agent.Version. Это значение можно проверить на наличие последней опубликованной версии агента. Ознакомьтесь с агента Azure Pipelines и проверьте страницу с наибольшим номером версии, указанным в списке.

6. Каждый агент автоматически обновляется при выполнении задачи, требующей более новой версии агента. Если вы хотите вручную обновить некоторых агентов, щелкните пул и выберите Обновить всех агентов.

Как убедиться, что у меня установлена последняя версия агента?

1. Перейдите на вкладку пулов агентов :

   1. Войдите в организацию (https://dev.azure.com/{yourorganization}).

   2. Выберите Azure DevOps, Настройки организации.

      

   3. Выберите пулы агентов .

      вкладка "Выбор пулов агентов"

   1. Войдите в коллекцию проектов (http://your-server/DefaultCollection).

   2. Выберите Azure DevOps, параметры коллекции.

      

   3. Выберите агентные пулы .

      

   1. Выберите Azure DevOps , параметры коллекции .

      

   2. Выберите агентские пулы .

      

2. Щелкните пул, содержащий агент.

3. Убедитесь, что агент включен.

4. Перейдите на вкладку возможностей:

   1. На вкладке пулов агентов выберите нужный пул агентов.

      

   2. Выберите агента и выберите нужного агента.

      

   3. Перейдите на вкладку Возможности.

      

      Заметка

      Размещенные корпорацией Майкрософт агенты не отображают системные возможности. Список программного обеспечения, установленного в агентах, размещенных корпорацией Майкрософт, см. в статье Использование размещенного корпорацией Майкрософт агента.

   1. На вкладке пулы агентов выберите нужный пул.

      

   2. Выберите агент и определите нужного агента.

      

   3. Выберите вкладку Возможности.

      вкладка "Возможности агента

   1. На вкладке пулы агентов выберите нужный пул.

      

   2. Выберите агент и определите нужного агента.

      

   3. Выберите вкладку Возможности.

      

5. Найдите функциональность Agent.Version. Это значение можно проверить на наличие последней опубликованной версии агента. Посмотрите раздел о агенте Azure Pipelines и проверьте страницу, чтобы найти наибольший номер версии, указанный в списке.

6. Каждый агент автоматически обновляется при выполнении задачи, требующей более новой версии агента. Если вы хотите вручную обновить некоторые из агентов, щелкните правой кнопкой мыши на пуле и выберите Обновить все агенты.

Где можно узнать больше о том, как работает запущенная служба?

Библиотека разработчиков Apple: Создание демонов и агентов запуска

Как запустить агент с самозаверяющим сертификатом?

Запуск агента с самоподписанным сертификатом

Как запустить агент через веб-прокси?

Запустить агент через веб-прокси

Как перезапустить агент

Если агент запущен в интерактивном режиме, смотрите инструкции по перезапуску в разделе Запуск в интерактивном режиме. Если вы запускаете агент в качестве службы, выполните действия, чтобы остановить, а затем запустить агента.

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

Предварительные требования TFVC

Если вы будете использовать TFVC, вам также потребуется Oracle Java JDK 1.6 или более поздней версии. (Для этой цели не хватает Oracle JRE и OpenJDK.)

модуль TEE используется для функциональности TFVC. Он имеет EULA, который необходимо принять во время настройки, если планируется работать с TFVC.

Так как подключаемый модуль TEE больше не поддерживается и содержит некоторые устаревшие зависимости Java, начиная с агента 2.198.0, он больше не включен в дистрибутив агента. Однако подключаемый модуль TEE загружается во время выполнения задачи извлечения, если вы извлекаете репозиторий TFVC. Подключаемый модуль TEE удаляется после выполнения задания.

Если агент работает за прокси-сервером или брандмауэром, необходимо принять, чтобы обеспечить доступ к следующему сайту: https://vstsagenttools.blob.core.windows.net/. Подключаемый модуль TEE скачан с этого адреса.

Если вы используете локальный агент и сталкиваетесь с проблемами с скачиванием TEE, вы можете установить TEE вручную:

1. Установите для среды DISABLE_TEE_PLUGIN_REMOVAL или переменной конвейера значение true. Эта переменная запрещает агенту удалять подключаемый модуль TEE после извлечения репозитория TFVC.
2. Скачайте TEE-CLC версию 14.135.0 вручную из релизов Team Explorer Everywhere на GitHub.
3. Извлеките содержимое папки TEE-CLC-14.135.0 в <agent_directory>/externals/tee.