GitHub Actions macOS Runner 2026: как настроить удалённый Mac?
Подключайте удалённый Mac как Runner GitHub Actions, если рабочему процессу действительно нужны Xcode или macOS, а репозиторий и источники запуска сборок заслуживают доверия. Сначала ограничьте доступ и триггеры, затем настройте службу Runner и проверьте её на реальном проекте; не открывайте узел с чувствительными данными для недоверенных запросов на слияние.
Это руководство для независимых разработчиков iOS-приложений, которым требуется собирать проекты в macOS через GitHub Actions.
Оно также пригодится небольшим командам, проверяющим права доступа, состояние службы и результаты сборки.
Если удалённый Mac уже есть, здесь можно оценить, подходит ли он для постоянного узла CI.
Перед подключением: оценка доступа и рисков
Runner — это компьютер, на котором выполняются задания рабочего процесса. Самостоятельно размещённый Runner использует выбранный вами Mac, а значит, рабочая задача получает доступ к среде и ресурсам, доступным учётной записи Runner. Это полезно для сборок, которым нужны Xcode и macOS, но требует отдельного решения по доверию к коду, правам репозитория и хранению секретов. В справочнике GitHub по самостоятельно размещённым Runner описаны их назначение и базовые свойства.
До регистрации зафиксируйте, какие репозитории будут отправлять задания на Mac, какие события запускают workflow и какие данные могут быть доступны задаче. Для первой проверки выбирайте доверенную ветку и ограничьте сценарий обычной компиляцией без подписи и публикации. Это позволит отдельно проверить работу Runner, не вовлекая сертификаты, ключи и учётные данные публикации.
Подойдёт ли самостоятельный Runner для публичного репозитория? Он может быть доступен в таком репозитории, однако разрешать выполнение на нём кода из недоверенных запросов на слияние — рискованное решение. GitHub предупреждает, что изменения из fork могут содержать код, способный получить доступ к среде Runner. Если публичный репозиторий принимает такие изменения, не направляйте их на узел, где хранятся секреты или доступны другие рабочие данные; подробности есть в предупреждении GitHub о безопасности Runner.
Сначала выберите область, в которой Runner будет зарегистрирован. Runner репозитория привязан к конкретному проекту; на уровне организации он может обслуживать несколько разрешённых репозиториев. Второй вариант удобен для общей инфраструктуры, но требует внимательнее управлять списком репозиториев, которым разрешено использовать узел. GitHub описывает управление такими разрешениями в документации по доступу к Runner.
| Условия проекта | Предпочтительная область | Условие остановки |
|---|---|---|
| Нужна проверка одного проекта, а доступ к другим репозиториям не требуется | Runner репозитория | Не расширяйте область только ради удобства, пока не проверены права и триггеры |
| Несколько доверенных проектов используют общий процесс сборки | Runner организации с явно ограниченным доступом | Не включайте репозитории, владельцы которых не контролируют код и события запуска |
| Публичный проект принимает код от внешних участников | Отдельная изолированная среда либо Runner без чувствительных секретов | Не запускайте недоверенный код на узле с доступом к внутренним данным |
| Задаче нужна только обычная сборка приложения | Runner с минимально необходимыми правами и без публикационных секретов | Не добавляйте подпись и загрузку артефактов в первую проверку |
Когда нужен именно GitHub Actions self-hosted runner? Выбирайте такой вариант, если сборке необходима среда macOS, доступная версия Xcode или особые локальные инструменты, а команда готова отвечать за доступность и обслуживание самого узла. Если работа не зависит от конкретного Mac, сначала уточните требования workflow: эта статья посвящена подключению удалённого Mac, а не сравнению стоимости разных способов выполнения задач.
До регистрации: подготовка macOS и Xcode
Перед настройкой Runner проверьте, что на Mac можно войти под выделенной учётной записью, а машина сохраняет сетевую доступность для GitHub. Убедитесь, что установлен именно полный Xcode, если проекту нужны его SDK, инструменты сборки или симулятор: наличие только командных инструментов не подтверждает готовность всей среды приложения.
Проверьте, какой каталог разработчика выбран в macOS:
xcode-select -p
Команда показывает текущий путь к каталогу разработчика. Если на Mac установлен полный Xcode и проект должен использовать его инструменты, проверьте выбор каталога командой xcode-select; Apple описывает настройку выбора командных инструментов в официальной документации. Установка инструментов командной строки и их назначение описаны отдельно в документации Apple по Xcode Command Line Tools.
Затем проверьте доступность xcodebuild и список проекта:
xcodebuild -version
xcodebuild -list -project "App.xcodeproj"
Замените имя проекта на фактическое. Если используется рабочая область, укажите её через параметр -workspace вместо -project. Вывод первой команды помогает увидеть выбранную установку Xcode, а второй — проверить, что проект распознаётся инструментом сборки. Это ещё не доказывает, что workflow сможет выполнить полный сценарий: сборка из среды службы может отличаться от ручного запуска в открытом графическом сеансе.
До регистрации также решите, будет ли Runner выполнять только компиляцию или ему понадобятся подписание и доступ к цепочке ключей. Для первоначальной проверки безопаснее оставить сертификаты и секреты вне задания. Если позднее понадобится подпись, её следует проектировать отдельно: доступ к ключам должен быть ограниченным, а условия запуска workflow — проверенными.
Успешный запуск
xcodebuildиз окна терминала подтверждает доступность инструмента в этом сеансе, но сам по себе не подтверждает наличие тех же переменных окружения, прав на цепочку ключей и графического контекста у фоновой службы.
Может ли Runner выполнять сборку Xcode? Да, если Mac располагает нужной установкой Xcode и workflow вызывает подходящий сценарий сборки. Сначала проверьте простой вызов xcodebuild без подписи, затем сравните его результат с запуском из службы Runner. Не считайте доступ к симулятору, ключам или графическому интерфейсу гарантированным только потому, что команда работает в интерактивном сеансе.
При регистрации: добавление Mac в GitHub Actions
Откройте настройки репозитория, организации или предприятия — в зависимости от выбранной области — и перейдите к добавлению Runner. GitHub выдаёт инструкции для выбранной системы и области; следуйте текущим командам в интерфейсе, а не копируйте старые команды из стороннего руководства. Изменение области регистрации может изменить, какие репозитории смогут назначать задания этому компьютеру.
На Mac создайте отдельный рабочий каталог для приложения Runner. Загрузите архив по адресу и с настройками, которые показывает GitHub, распакуйте его, а затем выполните конфигурацию по официальным указаниям. В этой статье намеренно не приводятся адреса загрузки и регистрационные токены: их следует брать из текущей страницы настройки целевого Runner. Не публикуйте токен в репозитории, журнале сборки, скриншоте или команде, сохранённой в общем документе.
При настройке укажите понятное имя и добавьте собственную метку, например ios-ci, чтобы workflow мог выбирать нужную машину. Не назначайте метки, предполагающие наличие оборудования или инструментов, которые не проверялись. Перед завершением убедитесь, что выбранная область соответствует плану доступа, а затем проверьте, появился ли Runner в списке узлов и отображается ли он как доступный.
В инструкции GitHub для приложения Runner различаются загрузка, конфигурация и запуск; при переходе к постоянной эксплуатации используйте официальное руководство по настройке приложения и службы. Если конфигурация не проходит, не расширяйте права наугад: сначала сверьте URL области, сетевую доступность, учётную запись macOS и актуальность команд, показанных GitHub.
Как подключить собственный Mac к GitHub Actions? Добавьте Runner в настройках нужного репозитория или организации, выполните предоставленные GitHub команды на Mac, назначьте метки и проверьте отображение узла в интерфейсе. Регистрационный токен используйте только для конфигурации и не переносите в workflow. После регистрации отдельно проверьте запуск задания: состояние «доступен» не заменяет проверку выполнения реальной сборки.
После регистрации: запуск службы и проверка сеанса
Для постоянной работы зарегистрируйте Runner как службу macOS по инструкции GitHub. В каталоге приложения используйте команды из установленного пакета, например:
./svc.sh install
./svc.sh start
./svc.sh status
Применимость этих команд и порядок работы службы зависят от конфигурации приложения; перед запуском сверяйтесь с актуальной инструкцией GitHub по службе Runner. После установки проверьте и состояние службы на Mac, и состояние Runner в GitHub. Если одно из них не подтверждается, не считайте узел готовым к автоматической сборке.
Служба необходима, когда задания должны выполняться без ручного запуска приложения после каждого входа в систему. Но фоновая служба и открытый пользовательский сеанс — не одно и то же. Переменные окружения, доступ к цепочке ключей, разрешения на файлы и графические операции могут различаться. Поэтому сначала проведите тест после запуска службы, а не только из обычного терминала.
| Проверка | Ожидаемое свидетельство | Если проверка не пройдена |
|---|---|---|
| Служба Runner запущена | Команда состояния службы и журнал не показывают ошибки запуска | Проверьте конфигурацию приложения и права учётной записи |
| Узел доступен в GitHub | В настройках выбранной области Runner отображается как доступный | Проверьте сеть, состояние службы и регистрацию |
| Workflow назначается этому узлу | В журнале задания видны ожидаемые метки и выбранный Runner | Сверьте runs-on, метки и область доступа |
| Xcode вызывается из задания | Лог содержит ожидаемый результат команды xcodebuild |
Сравните окружение службы с интерактивным сеансом |
| Перезапуск не требует ручного входа | После остановки и повторного запуска службы Runner возвращается в доступное состояние | Не переводите узел в ежедневную эксплуатацию до устранения причины |
Как поддерживать Runner доступным? Настройте его как службу macOS и проверьте автоматическое восстановление после остановки или перезапуска. Одного включения службы недостаточно: нужно подтвердить, что процесс действительно запущен, сеть доступна, а GitHub снова видит Runner. Подробности о состоянии узла и поиске причин сбоев приведены в руководстве GitHub по мониторингу и устранению неполадок.
При первом workflow: проверка сборки Xcode
Создайте workflow, который запускается только при отправке изменений в доверенную ветку. Для первой проверки достаточно получить код и выполнить команду сборки без подписи. Пример ниже показывает структуру: название ветки, имя проекта, схему и метку ios-ci необходимо адаптировать к репозиторию. Метка macOS предполагает, что она есть у зарегистрированного узла; если она отличается, используйте фактические метки Runner.
name: iOS build check
on:
push:
branches:
- main
permissions:
contents: read
jobs:
build:
runs-on: [self-hosted, macOS, ios-ci]
steps:
- name: Checkout source
uses: actions/checkout@<зафиксированная-версия>
- name: Inspect project
run: xcodebuild -list -project "App.xcodeproj"
- name: Build for simulator
run: >
xcodebuild
-project "App.xcodeproj"
-scheme "App"
-configuration Debug
-destination 'generic/platform=iOS Simulator'
CODE_SIGNING_ALLOWED=NO
build
Значение contents: read ограничивает разрешения токена workflow чтением содержимого репозитория; набор доступных разрешений описан в справке GitHub по синтаксису workflow. Укажите для actions/checkout версию, одобренную командой и закреплённую по её правилам обновления. Не используйте пример с незаполненным номером версии как готовую конфигурацию.
Первая задача должна проверять только несколько вещей: GitHub выбрал нужный Runner, checkout получил ожидаемый код, а xcodebuild завершился без ошибки. Документация GitHub объясняет, как выбирать самостоятельно размещённые Runner в workflow и применять метки, — см. инструкцию по использованию Runner в workflow. Если задание остаётся в очереди, проверьте совпадение меток и область, в которой Runner зарегистрирован. Если оно запустилось не на том узле, остановите дальнейшие тесты и исправьте выбор Runner до добавления других задач.
Как выполнять автоматическую сборку iOS на удалённом Mac? Сначала подключите Runner и используйте runs-on с метками именно этого узла, затем запустите workflow на доверенной ветке и проверьте лог вызова xcodebuild. Не добавляйте архивирование, подпись и загрузку в первом тесте: так проще определить, вызвана ли ошибка планированием, checkout, конфигурацией проекта или уже отдельным этапом выпуска.
После успешной компиляции сохраните журнал задания и зафиксируйте, какой проект, схема и конфигурация проверялись. Если ожидается архив, добавьте его отдельным этапом и проверьте результат в соответствии с требованиями проекта; не приравнивайте успешную сборку для симулятора к готовому подписанному архиву. Автоматическую публикацию также проектируйте отдельно, с независимой проверкой секретов и событий, которые могут запустить загрузку.
Если рабочий процесс требует доступа к сертификатам, ключам или учётной записи публикации, сначала подтвердите, кто может запустить соответствующий job. Успешный тест компиляции не является основанием помещать секреты в Runner, доступный для кода из недоверенных источников.
При приёмке: доказательства готовности и обслуживание
Перед повседневным использованием соберите доказательства для каждой части цепочки, а не ограничивайтесь зелёной отметкой задания. Минимальная приёмка включает доступность Runner в GitHub, корректное назначение workflow, читаемый журнал сборки, соответствие результата ожиданиям проекта и восстановление после остановки службы. Если проекту нужен архив, добавьте его наличие и проверку как отдельный критерий.
Для небольшой команды полезно записать владельца узла, допустимые репозитории, разрешённые события запуска, используемые метки, способ обновления приложения Runner и порядок временного отключения. При каждом изменении доступа проверяйте не только настройки репозитория, но и события workflow: расширение триггеров может фактически открыть узел коду, который ранее не выполнялся на нём.
Обслуживание включает обновление Runner по текущим рекомендациям GitHub, проверку сетевой доступности и анализ журналов при отказах. Перед обновлением или изменением конфигурации определите, как остановить узел и вернуть предыдущую рабочую конфигурацию. Если Runner больше не нужен, удалите его из области GitHub и очистите локальную конфигурацию по официальным инструкциям, чтобы в списке не оставался неиспользуемый узел.
Сверяйте полномочия workflow при добавлении новых действий и задач, особенно если меняется работа с секретами. В журнале должны быть различимы этапы получения кода и вызова Xcode, но не должны появляться токены, приватные ключи или содержимое секретов. Если диагностика требует включить подробное логирование, заранее проверьте, какие значения могут попасть в вывод.
Условия решения
- Если сборка требует Xcode или macOS, а все источники запуска контролируются командой, регистрируйте удалённый Mac как Runner и начинайте с изолированной задачи компиляции.
- Если репозиторий публичный и принимает недоверенные изменения, не направляйте такие задания на Mac с чувствительными секретами; выберите отдельную изолированную среду или пересмотрите триггеры.
- Если Runner доступен, но служба не восстанавливается самостоятельно, отложите ежедневное использование и сначала исправьте запуск и сетевую доступность.
- Если сборка проходит, но архив или подпись не проверены, считайте подтверждённой только компиляцию; выпускные этапы принимайте отдельно.
- Если узел используется только время от времени, а постоянное обслуживание не оправдано, сравните его с другими вариантами выполнения задач, прежде чем оставлять Mac постоянно включённым.
Когда сборки завязаны на личный Mac разработчика, компьютер может быть выключен или занят другой работой, а состояние пользовательского сеанса и его доступ к инструментам приходится учитывать отдельно. Перенос Runner на удалённый Mac убирает зависимость от рабочего компьютера, но не отменяет настройку службы, сетевой контроль и безопасное управление секретами. Если постоянный узел нужен лишь на период разработки или тестирования процесса, можно изучить консоль удалённого Mac KuzCloud и справочные материалы KuzCloud, а затем оценить, подходит ли аренда для конкретного графика сборок. Для стабильной длительной нагрузки или задач, которым необходим физический доступ к оборудованию, сначала сопоставьте аренду с собственной машиной и другими вариантами инфраструктуры: решающим должно быть соответствие рабочего процесса, а не сам факт удалённого доступа.
Запустите CI/CD на выделенном удалённом Mac
KuzCloud предоставляет физический Mac mini M4 для сборок и тестирования проектов под macOS без покупки собственного оборудования.
Получите полный root-доступ и подключайтесь к узлу по SSH или через удалённый рабочий стол.