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

Что нужно заранее

• Кластер Buildkite и права на управление его токенами агентов и очередями. Нужно быть администратором организации или maintainer кластера.
• Mac на macOS 11 или новее. Это минимум, который указывает Buildkite. Apple silicon, Homebrew, Xcode и права администратора.
• SSH-ключ, которым агент сможет клонировать ваши репозитории.

1. Создайте очередь и токен агента

В Buildkite выберите Agents, чтобы попасть на страницу Clusters, и выберите свой кластер. На странице Queues нажмите New Queue. Задайте ключ macos и выберите Self hosted. Затем откройте Agent Tokens, нажмите New Token, добавьте описание и создайте токен. Скопируйте значение. Buildkite показывает его один раз.

В форме токена есть поле Allowed IP Addresses. На MacRun оставьте его пустым. У наших Mac нет статического публичного IP, поэтому правило CIDR не пустит агента.

2. Установите агент через Homebrew

brew tap buildkite/buildkite
brew trust buildkite/buildkite
brew install buildkite/buildkite/buildkite-agent

Homebrew 7.0.7, версия на нашем Mac в октябре 2026 года, отказывается ставить формулы из стороннего tap, пока вы ему не доверитесь. Для этого нужна средняя строка. Формула теперь называется buildkite-agent@3, а старое имя из документации Buildkite по-прежнему на неё указывает.

На Apple silicon файлы лежат в /opt/homebrew:

• Конфигурация: /opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
• Хуки: /opt/homebrew/etc/buildkite-agent/hooks
• Лог: /opt/homebrew/var/log/buildkite-agent.log

Выполните brew info buildkite-agent, чтобы увидеть точные пути на своей машине.

3. Добавьте токен и тег очереди

Документация Buildkite заменяет токен-заглушку через sed. Замените текст заглавными буквами своим токеном.

sed -i '' "s/xxx/INSERT-YOUR-AGENT-TOKEN-HERE/g" "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg
cat "$(brew --prefix)"/etc/buildkite-agent/buildkite-agent.cfg | grep token

Затем откройте тот же файл и задайте строку tags, чтобы агент вошёл в вашу очередь:

tags="queue=macos"

Агент принадлежит одной self-hosted очереди в кластере. Без тега очереди он попадает в очередь по умолчанию. Если в кластере нет self-hosted очереди по умолчанию, Buildkite пишет, что агент не сможет подключиться.

4. Проверьте, затем запустите как службу

Один раз запустите агента на переднем плане. Он должен появиться в списке агентов кластера.

buildkite-agent start

Остановите его через Control C. Формула Homebrew содержит описание службы. Она запускает buildkite-agent start с конфигурацией выше, перезапускается при сбое и пишет лог в тот же файл. Запустите её из Terminal на рабочем столе Mac:

brew services start buildkite/buildkite/buildkite-agent@3
brew services list | grep buildkite

На macOS агент работает от пользователя, который запустил службу launchd. Запускайте её под учётной записью, которой принадлежат Xcode и ваши ключи подписи.

Начните с одного агента на Mac. Buildkite описывает настройку spawn в конфигурационном файле и флаг --spawn, чтобы запускать несколько агентов из одной службы. Две сборки Xcode одновременно делят одни и те же ядра и память. На машине с 16 GB сначала замерьте одного агента, а потом пробуйте двух.

5. Сделайте так, чтобы он переживал перезагрузку

В заметках к установке формулы сказано настроить Mac на автоматический вход под этим пользователем. README у tap от Buildkite объясняет компромисс. LaunchAgent требует входа в систему, зато позволяет тестам использовать графические инструменты, например iOS Simulator. Включите автоматический вход в System Settings, в разделе Users and Groups. Затем отключите сон, перезагрузите Mac и проверьте список агентов.

sudo pmset -a sleep 0
sudo shutdown -r now

Держите plist в папке LaunchAgents внутри домашней папки. Туда его и кладёт Homebrew. На macOS 27 мы видели, как plist в /Library/LaunchAgents ломает автовход. Подробнее в статье об автовходе на headless Mac.

6. Шаг пайплайна для Mac

steps:
  - label: ":xcode: iOS tests"
    agents:
      queue: "macos"
    commands:
      - "rm -rf build/TestResults.xcresult"
      - "xcodebuild test -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.5' -resultBundlePath build/TestResults.xcresult"
      - "ditto -c -k --keepParent build/TestResults.xcresult build/TestResults.xcresult.zip"
    artifact_paths:
      - "build/TestResults.xcresult.zip"
    timeout_in_minutes: 30
    retry:
      automatic:
        - exit_status: -1
          limit: 2

Повтор с exit_status: -1 взят из примера command step в документации Buildkite. Он повторяет задачу, когда потерялся сам агент, а не когда упал тест.

Частые ошибки и их решения

• launchctl пишет Could not find domain for. Buildkite объясняет, что на Mac должен быть выполнен вход пользователя. Войдите на рабочий стол и загрузите службу снова.
• Refusing to load formula ... from untrusted tap. Выполните brew trust buildkite/buildkite и установите снова.
• Агент не подключается. Токен неверный, или ключа очереди из tags в этом кластере нет.
• Агент не может клонировать репозиторий. Положите ключ в ~/.ssh пользователя, от которого работает агент.
• xcodebuild: error: Existing file at -resultBundlePath. Сборки используют один и тот же checkout. Сначала удалите bundle, как выше.

Чтобы потом обновиться, выполните brew update && brew upgrade buildkite/buildkite/buildkite-agent@3.

Чем помогает выделенный Mac

Buildkite создан для ваших собственных машин, а постоянный Mac хранит свои кэши. В нашем тесте на iOS-приложении Wikipedia с Xcode 26.6 задача после небольшого изменения заняла 27 секунд на прогретом M6. Свежий hosted раннер macos-26 у GitHub потратил 269 секунд.

Когда хватает hosted агентов Buildkite

У Buildkite есть и hosted агенты на macOS. По документации, которую мы читали в октябре 2026 года, их выбирают при создании hosted очереди. Если не хочется следить ни за какой машиной, это более простой путь. MacRun также не подойдёт, если нужны SLA, статический IP для правил токена или больше одного региона.

Сторона MacRun описана на странице о других CI-системах. Что запускать в шагах, объясняет руководство по пайплайну CI/CD для iOS.