GitHub Actions macOS self-hosted Runner: настройка и приёмка в 2026 году

По документации GitHub, задание с runs-on попадает на self-hosted Runner только при совпадении всех заданных меток маршрутизации. Поэтому рабочий вывод прост: если сборка зависит от Xcode, подписи кода, симулятора или Apple Silicon и запускается регулярно, имеет смысл использовать реальный Mac как постоянный узел GitHub Actions macOS self-hosted Runner. Для редких задач без фиксированного toolchain обычно рациональнее оставить управляемый Runner и не оплачивать постоянное администрирование.

Этот материал предназначен для iOS-разработчиков, работающих на Windows или Linux, которым нужен закреплённый macOS CI/CD. Он также пригодится DevOps-инженерам, контролирующим версии Xcode, сертификаты, кэш и очередь сборок, а также небольшим командам, сравнивающим покупку Mac mini с периодическим использованием удалённого Mac.

Последняя проверка: 3 сентября 2026 года. Процедуры сверены с документацией GitHub, требованиями Apple к Xcode и официальными материалами actions/runner.

До подключения: проверка пригодности узла

Реальный Mac оправдан не самим фактом использования GitHub Actions, а ограничениями конкретного проекта. До регистрации Runner следует зафиксировать матрицу инструментов и доверия.

Self-hosted Runner подходит, если выполняется хотя бы одно из условий:

• проект собирается в Xcode и требует macOS toolchain;
• workflow использует кодовую подпись, provisioning profile или доступ к Keychain;
• тесты запускаются в iOS Simulator;
• команда должна закрепить конкретную версию Xcode и macOS;
• сборка должна выполняться на Apple Silicon;
• нужен постоянно доступный узел для очереди Mac CI/CD, а не случайный запуск по расписанию.

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

Важна и модель доверия. Self-hosted Runner не следует воспринимать как одноразовую виртуальную среду: на нём могут остаться исходники, кэш, временные файлы, логи и инструменты. Публичный pull request или код внешнего автора нельзя по умолчанию направлять на узел, где находятся production-сертификаты. В документации GitHub отдельно описаны риски использования self-hosted Runner в workflow из недоверенных репозиториев и веток — правила доступа и безопасности нужно определить до установки.

Для небольшой команды полезно заранее разделить два контура:

1. обычный Runner без секретов для тестов, линтеров и сборки без подписи;
2. доверенный Runner для release-сборок, который доступен только защищённым веткам и одобренным workflow.

Если физический Mac находится в дата-центре, доступ к нему должен предоставляться через защищённый административный канал. SSH удобен для установки и диагностики, а VNC или веб-консоль — для операций, где требуется графический интерфейс. При этом удалённый доступ не заменяет разграничение прав внутри macOS.

Первый час: отдельный пользователь и регистрация

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

Подготовьте:

• отдельную учётную запись macOS для Runner;
• каталог, предназначенный только для рабочих файлов GitHub Actions;
• установленный Git и менеджер зависимостей проекта;
• требуемую версию Xcode;
• SSH-доступ для диагностики;
• правило очистки временных файлов после задания.

Официальный пакет скачивается из репозитория actions/runner. Версию следует брать из актуального списка релизов, а не копировать старую ссылку из стороннего руководства: страница Releases показывает опубликованные версии и заметки к ним.

Регистрация выполняется в настройках нужного уровня — репозитория, организации или предприятия. GitHub выдаёт временный registration token; его нельзя хранить в репозитории, скрипте автоматического развёртывания или общем чате. Порядок действий выглядит так:

1. Войти в GitHub под учётной записью с правом добавления Runner.
2. Открыть настройки репозитория или организации и перейти к разделу Actions и self-hosted runners.
3. Выбрать macOS и архитектуру, соответствующую реальному узлу.
4. Скачать пакет под отдельного системного пользователя.
5. Распаковать его в изолированный каталог.
6. Запустить команду конфигурации с временным токеном.
7. Назначить понятное имя узла и рабочий каталог.
8. Добавить базовые метки self-hosted, macOS, ARM64, если Mac использует Apple Silicon.
9. Добавить назначение, например ios-build или release-signing.
10. Проверить, что Runner появился в GitHub со статусом online.

Точная команда зависит от версии пакета и инструкции, показанной GitHub для выбранного уровня регистрации. Поэтому безопаснее копировать параметры из текущей страницы добавления Runner, а не переносить команду из статьи, написанной для другой версии.

Метку ARM64 нельзя добавлять только потому, что это желательная архитектура. Она должна соответствовать фактическому узлу. Для проверки можно использовать:

uname -m
sw_vers
xcodebuild -version

Команды показывают архитектуру, версию macOS и активную версию Xcode. Их результат следует сохранить в журнале приёмки.

Первый workflow: минимальный замкнутый цикл

Первый запуск не должен одновременно проверять подпись, кэш, тесты, архив и публикацию. Если всё включить сразу, ошибка маршрутизации смешается с ошибкой Xcode или Keychain. Сначала нужно доказать четыре вещи: задание нашло нужный Runner, репозиторий склонировался, shell-команды выполняются, рабочий каталог очищается.

Минимальный workflow может выглядеть так:

name: macOS runner smoke test

on:
  workflow_dispatch:

jobs:
  probe:
    runs-on: [self-hosted, macOS, ARM64, ios-build]

    steps:
      - name: Check out source
        uses: actions/checkout@v4

      - name: Inspect environment
        shell: bash
        run: |
          set -euo pipefail
          uname -a
          sw_vers
          xcodebuild -version
          git --version

      - name: Unsigned build
        shell: bash
        run: |
          set -euo pipefail
          xcodebuild \
            -workspace App.xcworkspace \
            -scheme App \
            -configuration Debug \
            -sdk iphonesimulator \
            CODE_SIGNING_ALLOWED=NO \
            build

Версия actions/checkout в этом примере является частью демонстрационного workflow, а не универсальным требованием для каждого проекта. Рабочую версию action следует закреплять согласно политике команды и проверять перед внедрением.

Если задание долго стоит в очереди, сначала сравниваются массив runs-on и labels узла. GitHub требует совпадения всех меток, поэтому Runner только с self-hosted, macOS и ARM64 не примет задание, которому дополнительно нужна ios-build. Подробное описание этого механизма приведено в документации по использованию labels.

После успешной безымянной сборки добавляются этапы в таком порядке:

• установка зависимостей;
• модульные и UI-тесты;
• архивирование;
• импорт сертификата;
• подпись;
• загрузка артефакта;
• очистка.

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

find "$RUNNER_WORKSPACE" -maxdepth 2 -type f -name "*.p12" -o -name "*.mobileprovision"

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

Первый день: Xcode, подпись и кэш

Для Xcode 26 нельзя исходить из предположения, что любая версия macOS подойдёт. Совместимость нужно проверить по официальным системным требованиям Xcode от Apple. Если проект обновляет Xcode, одновременно следует проверить минимальную версию macOS, доступность нужных SDK и поведение Simulator.

На узле желательно иметь явный механизм выбора Xcode. Например:

sudo xcode-select --switch /Applications/Xcode.app
xcodebuild -version

Путь должен соответствовать реально установленному приложению. Если рядом находятся несколько копий Xcode, workflow обязан проверять активный developer directory перед сборкой. Иначе один и тот же commit может собираться разными SDK в зависимости от состояния узла.

Версии зависимостей тоже фиксируются:

• lock-файл должен входить в commit;
• Ruby, Bundler, Node.js или Python следует устанавливать предсказуемым способом;
• команды установки должны завершаться с ошибкой при несовпадении версии;
• изменения toolchain должны менять ключ кэша.

Кэш зависимостей, кэш DerivedData и финальные артефакты — разные сущности. Их нельзя складывать в один каталог без политики срока хранения. Упрощённый ключ должен учитывать lock-файл, операционную систему и toolchain:

- name: Cache dependencies
  uses: actions/cache@v4
  with:
    path: |
      vendor/bundle
      .build
    key: macos-${{ runner.arch }}-${{ hashFiles('**/Gemfile.lock', '**/Package.resolved') }}

Этот пример требует адаптации под конкретный проект. Кэш не должен содержать сертификаты, пароли, provisioning profiles или файлы, полученные из защищённых секретов.

Подпись включается только после успешного unsigned build. Сертификат импортируется в отдельный Keychain непосредственно перед подписываемыми действиями. После архивации нужно закрыть или удалить временный Keychain, удалить профиль и проверить, что секреты не записались в лог через set -x, диагностический вывод или сообщение об ошибке.

Важно: узел с production-сертификатом должен быть доступен только доверенному workflow. Даже если pull request выглядит безобидным, его скрипты получают возможность выполнять команды на Runner с теми правами, которые предоставлены системному пользователю.

Секреты GitHub нужно ограничивать окружением release и защищёнными ветками. Для публичного проекта безопасная схема обычно означает отсутствие signing secrets в workflow обычного pull request. Такой подход не ускоряет каждую проверку, зато не превращает внешний код в путь к ключам подписи.

Первая неделя: служба, группы и наблюдаемость

Ручной запуск Runner из терминала недостаточен для постоянного узла. После установки пакета конфигурацию следует оформить как службу macOS через скрипт svc.sh, который поставляется с actions/runner. Конкретный способ запуска и права зависят от версии пакета, поэтому команды нужно брать из текущего файла и официальной инструкции, а не из устаревшего сниппета.

Проверка после установки должна включать:

• состояние службы launchd;
• наличие Runner online в GitHub;
• перезапуск Mac;
• повторное появление Runner online;
• запуск тестового workflow после восстановления;
• наличие диагностических логов при неудаче.

Если Runner offline, проверяются сетевой маршрут, DNS, доступ к GitHub, состояние службы и пользователь, от имени которого выполняется процесс. Справочная страница GitHub по self-hosted Runner описывает ограничения среды и общую модель работы узла.

Группы Runner помогают отделить тестовые и release-узлы. Например, одна группа может обслуживать внутренние сборки без подписи, другая — только защищённые workflow с сертификатами. Метки описывают технические свойства и назначение, а группа задаёт более широкий контур доступа. Не следует использовать одну универсальную метку вроде macos для всех типов задач, если часть узлов имеет разные Xcode или разные секреты.

Обновления также должны быть управляемыми. Команда фиксирует окно для:

• обновления actions/runner;
• обновления macOS;
• обновления Xcode;
• пересборки зависимостей;
• проверки сертификатов и профилей;
• перезапуска и контрольной сборки.

Официальный проект Runner публикует изменения в журнале релизов. Перед обновлением production-узла необходимо проверить smoke test и иметь возможность вернуться к рабочей версии. Автоматически принимать любое обновление без тестового окна рискованно для проекта с жёстко закреплённым Xcode.

Минимальная диагностика очереди выглядит так:

1. Сверить все labels в runs-on.
2. Проверить, что Runner online, а не только зарегистрирован.
3. Убедиться, что узел принадлежит нужной группе.
4. Проверить, что workflow имеет право использовать эту группу.
5. Посмотреть состояние launchd и логи службы.
6. Проверить свободное место и завершившиеся процессы предыдущего задания.
7. Повторить запуск на минимальном smoke test.

Длительная очередь при online-статусе почти всегда требует проверки маршрутизации, группы или занятости узла; сам статус online не доказывает, что конкретное задание соответствует его labels.

Перед запуском в production: приёмочная матрица

До передачи узла команде нужно зафиксировать не только факт успешной сборки, но и условия, при которых она была выполнена. В журнале должны быть указаны Mac, архитектура, версия macOS, версия Xcode 26 или другой утверждённый toolchain, commit, тип сборки и результат очистки.

Область	Прошло	Требует исправления	Не подходит
Маршрутизация	Все labels совпадают, задание получает нужный Runner	Используется слишком общая или ошибочная метка	Нельзя отделить доверенные и внешние workflow
Toolchain	Xcode и macOS соответствуют требованиям Apple	Версии меняются вручную и не фиксируются	Проект требует SDK, которого нет на узле
Подпись	Секреты доступны только release-шагу	Keychain закрывается не во всех ветках ошибки	Нельзя изолировать production-сертификаты
Служба	После перезапуска Runner снова online	Восстановление требует ручного входа	Узел регулярно теряет связь или зависает
Кэш и очистка	Lock-файлы участвуют в ключе, секреты удаляются	Остаются DerivedData или временные профили	Нет безопасной процедуры очистки
Доверие к коду	Публичные PR не видят signing Runner	Правила доступа не документированы	Внешний код неизбежно получает production-доступ
Отказоустойчивость	Есть smoke test и порядок отката	Диагностика выполняется только вручную	Нет резервного пути для срочного release

Полный приёмочный прогон должен включать холодный запуск workflow, восстановление зависимостей, безымянную компиляцию, тесты, архивирование, подписываемую сборку, загрузку артефакта и повторный запуск после перезагрузки узла. Время каждой операции следует измерять в собственной среде и привязывать к commit и состоянию кэша. Без таких условий сравнение с другим Mac или другим способом размещения будет недостоверным.

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

Выбор схемы размещения

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

Периодическая аренда удалённого Mac разумнее, когда команда не хочет приобретать оборудование, требуется временный проектный узел или нужно быстро проверить совместимость Xcode и Apple Silicon. Перед выбором стоит изучить условия аренды Mac у nuvcloud, а затем сопоставить срок использования с трудозатратами на обслуживание.

Для администрирования полезно заранее подготовить руководство по доступу и настройке удалённого Mac. Если главная задача — безопасные подключения инженеров, дополнительно следует проверить политику конфиденциальности nuvcloud и сопоставить её с внутренними требованиями проекта.

Частые вопросы

FAQ вынесен отдельно, чтобы короткие ответы не смешивались с пошаговой процедурой. Для production-окружения решающими остаются не только наличие удалённого Mac, но и архитектура, labels, права доступа, состояние службы и порядок удаления секретов.

Итог для выбора

Текущая схема на Windows или Linux с Linux-сервером удобна для большинства backend-задач, но не заменяет macOS там, где требуются Xcode, iOS Simulator, Apple Silicon или кодовая подпись. Виртуализация и непостоянные удалённые среды добавляют несовместимость SDK, неопределённость с Keychain и дополнительную диагностику сети. Покупка Mac mini, в свою очередь, требует единовременных затрат, постоянного питания, контроля обновлений и самостоятельного восстановления после аппаратных или сетевых проблем.

Если нужен долгоживущий Mac CI/CD-узел без покупки и обслуживания собственного устройства, аренда реального Mac у nuvcloud может быть более управляемым вариантом. После проверки доступной конфигурации, срока аренды и способа подключения Runner можно развернуть по приведённому чек-листу, ограничить signing workflow и использовать узел как контролируемую часть production-контура, а не как временный компьютер разработчика.