Сначала разделите проблему на три случая: Runner офлайн, исполнитель онлайн, но задание не назначается, или сборка уже началась и завершилась ошибкой; затем проверяйте только соответствующий слой — доступность Mac, сеть, метки и группы, службу launchd либо журналы выполнения. На этой неделе зафиксируйте последний успешный запуск и время появления сбоя: это позволит отличить неисправность хоста от ошибки конфигурации без преждевременной замены Mac.
Руководство пригодится инженерам, которые поддерживают самостоятельный GitHub Actions Runner для сборки приложений под iOS и macOS.
Разработчики с долгой очередью проверят, совпадают ли метки workflow и исполнителя.
Руководители команд смогут решить, исправлять конфигурацию или менять схему размещения Mac.
От офлайн-статуса к ошибке сборки: сначала определите симптом
В интерфейсе GitHub Actions состояние исполнителя и состояние задания — не одно и то же. Runner может быть офлайн, онлайн и свободен либо занят; workflow при этом может ожидать подходящего исполнителя, уже выполняться или завершиться неудачно. Официальное описание состояний и порядка диагностики self-hosted Runner помогает начать с наблюдаемого статуса, а не с предположения о неисправности оборудования.
Перед изменением настроек запишите название репозитория, workflow и job, точное сообщение в интерфейсе, время последнего успешного выполнения и момент, когда началась проблема. Затем сопоставьте эти сведения с журналом конкретного запуска. Если работа завершилась ошибкой уже после старта шага, Runner, скорее всего, принял задание: искать причину нужно в команде сборки, зависимостях, разрешениях или окружении проекта.
| Наблюдаемый симптом | Первый уровень проверки | Что пока не следует менять |
|---|---|---|
| Runner помечен как офлайн | Состояние Mac, процесс Runner, исходящее подключение к GitHub | Метки workflow и настройки сборочного скрипта |
| Runner онлайн, job ждёт | Свободен ли исполнитель; совпадают ли метки и группа | macOS и инструменты сборки без доказательств сбоя |
| Job стартовал, затем упал | Логи workflow, Runner и команда, завершившаяся ошибкой | Сетевую конфигурацию, если соединение сохранялось |
В документации GitHub маршрутизация задания описана через доступность подходящего self-hosted Runner. Поэтому запись «онлайн» не доказывает, что конкретный job может быть назначен именно этому исполнителю: проверяйте не только присутствие узла, но и его состояние и соответствие требованиям задания. Правила маршрутизации self-hosted Runner полезны для этого разграничения.
Офлайн: Mac и соединение против повторной регистрации
Если Runner отображается офлайн, начните с самого Mac. Проверьте, включён ли компьютер, подключён ли он к сети и не уходит ли в режим, который прерывает работу службы. Если это физическая машина в офисе, отдельно проверьте питание и сетевое подключение. Если Mac доступен через SSH, используйте подключение, чтобы проверить процесс и журналы, а не делайте вывод о состоянии хоста только по веб-интерфейсу GitHub.
В каталоге установки Runner выполните штатную проверку соединения:
cd /путь/к/actions-runner
./config.sh --check
Запускайте проверку из каталога установленного Runner и сохраняйте её результат вместе со временем запуска. Если соединение не проходит, проверяйте DNS, правила исходящего доступа, сетевой прокси и доверие к сертификатам в окружении, где работает служба. Успешная проверка с ноутбука разработчика не гарантирует, что тот же маршрут доступен Mac: это могут быть разные сети, настройки прокси или учётные контексты.
Для диагностики посмотрите файлы Runner в каталоге _diag:
ls -lt _diag | head
Сопоставьте отметки времени в диагностических файлах со временем появления офлайн-статуса. Ищите сообщения о разрыве соединения, ошибке разрешения имени или отказе при установлении защищённого соединения; не считайте сам факт наличия записи доказательством конкретной причины. Для дополнительных сведений о работе Runner GitHub описывает включение расширенного журналирования Actions.
Не отключайте проверку TLS как обычный способ «починить сеть». Если соединение ломается на проверке сертификата, выясните, какой сертификат или сетевой прокси видит именно служба Runner, и восстановите корректную цепочку доверия.
Если Mac включён, соединение подтверждено, но Runner остаётся офлайн, проверьте процесс и конфигурацию установленного экземпляра. Не удаляйте его и не регистрируйте заново, пока не сохраните журналы и не подтвердите, что это действительно необходимо: повторная регистрация может скрыть последовательность событий, не устранив сетевую или сервисную причину.
Онлайн, но задания стоят: метки против доступа к группе
Когда Runner доступен, но job не назначается, проверяйте правила маршрутизации. В runs-on могут быть указаны метки, по которым GitHub выбирает исполнителя. При нескольких метках кандидат должен удовлетворять всем заданным условиям; сравнивайте их с метками, показанными для конкретного Runner, а не с тем, что вы помните о настройке.
Пример workflow:
runs-on: [self-hosted, macOS, ARM64]
Этот пример означает, что нужны все указанные метки. Сверьте фактические значения в настройках Runner с файлом workflow и проверьте написание, регистр и изменения после редактирования конфигурации. Официальные правила использования меток и групп в workflow описывают, как GitHub выбирает подходящий узел.
Отдельно проверьте, разрешена ли группа Runner для нужного репозитория или организации. Исполнитель может быть онлайн, а job всё равно останется в очереди, если репозиторию недоступна группа, в которой он зарегистрирован. Права доступа проверяются в настройках группы; описание доступа к self-hosted Runner поможет отличить ограничение прав от несоответствия меток.
Убедитесь и в том, что Runner не занят другим заданием. Не меняйте несколько меток и разрешений одновременно: сначала зафиксируйте исходную конфигурацию, затем изменяйте одно условие и повторно запустите тот же workflow. Так вы поймёте, какое именно правило мешало маршрутизации.
После перезагрузки: интерактивный запуск против launchd
Если Runner работает после ручного запуска, но теряет связь после перезагрузки, интерактивный запуск не подтверждает исправность службы. Служба работает в собственном контексте запуска, поэтому профиль пользователя, переменные окружения, доступ к файлам и настройки сети могут отличаться от терминальной сессии. Именно это различие часто приводит к неверному выводу «команда работает, значит, служба настроена».
Перейдите в каталог установки и запросите состояние службы:
cd /путь/к/actions-runner
sudo ./svc.sh status
Если служба остановлена, сначала проверьте, что она зарегистрирована и запускается от ожидаемой учётной записи. Документация GitHub по настройке приложения Runner и службе macOS описывает управление службой; сверяйте команды с инструкциями для установленной версии Runner. Не заменяйте проверку службы разовым запуском процесса в терминале: после выхода из сессии такой процесс может прекратиться.
Проверьте журналы Runner за время перезагрузки и сопоставьте их с результатом status. Если служба не стартовала, ищите сбой регистрации, прав доступа или запуска. Если она запущена, но GitHub показывает офлайн, возвращайтесь к проверке сети из контекста службы. Когда ручной запуск проходит, а запуск через launchd нет, отдельно изучайте окружение процесса и доступ к зависимостям проекта.
Не редактируйте системные файлы launchd наугад. Сначала сохраните текущее состояние службы и журналы; затем меняйте только тот параметр запуска, для которого есть подтверждённая ошибка.
Job уже запущен: журналы Runner против журналов workflow
Если задание принято, но сборка падает, разделите диагностику на два слоя. Журнал workflow показывает порядок шагов, вывод команд и место завершения job. Диагностические файлы Runner в _diag помогают понять работу агента при получении и выполнении задания. Используйте документацию по просмотру логов workflow и сопоставляйте события по времени.
Сначала найдите последний выполненный шаг и команду, которая вернула ошибку. Если упал xcodebuild, установка пакета или пользовательский скрипт, проверяйте доступность зависимостей, выбранную версию инструмента, переменные окружения и права на проект. Если job не дошёл до ожидаемого шага либо Runner терял связь во время выполнения, изучайте диагностические журналы агента. Не приписывайте сбой конкретному поколению оборудования без подтверждения из логов или воспроизводимого теста.
Сверяйте фактический запуск с текущими требованиями проекта. Например, сборка может зависеть от секрета, недоступного для конкретного события workflow, или от файла, который есть в интерактивной сессии, но не в окружении службы. Повторите запуск с теми же параметрами, зафиксируйте шаг и сообщение об ошибке, а затем меняйте только одну переменную. Так вы не смешаете сбой кода с неполадкой Runner.
Проверка перед изменением конфигурации
Используйте список как точку принятия решения: отмечайте только то, что проверили, а не то, что кажется вероятным.
- [ ] Я записал статус Runner и job, название workflow, время ошибки и последний успешный запуск.
- [ ] Я подтвердил, что Mac доступен, и проверил состояние Runner в каталоге установки.
- [ ] Я выполнил сетевую проверку на самом Mac, а не на другой машине в той же команде.
- [ ] Я сверил каждую метку
runs-onс реальными метками исполнителя. - [ ] Я проверил, что группа Runner доступна репозиторию или организации.
- [ ] Я проверил службу через
sudo ./svc.sh status, а не только запуск из терминала. - [ ] Я сопоставил время сбоя в логах workflow и файлах
_diag. - [ ] Я нашёл конкретное условие, которое меняю, и сохранил исходное состояние.
Если не отмечены пункты о метках или группе, исправьте маршрутизацию и повторите job на том же Mac. Если не подтверждены служба или сеть, сначала устраните эту причину. Переезд на другой хост не исправит ошибочный runs-on, нехватку разрешений или скрипт сборки.
Сравнение причин: настройка против инфраструктуры
| Причина | Признак, который её подтверждает | Разумное следующее действие |
|---|---|---|
| Несовпадение меток | Runner онлайн, а условия runs-on не совпадают |
Исправить workflow или метки |
| Ограничение группы | Исполнитель существует, но репозиторию группа не разрешена | Проверить область доступа и права |
| Ошибка службы | Ручной запуск возможен, служба не активна после перезагрузки | Разобрать регистрацию и журналы launchd |
| Сбой сети или хоста | Проверка соединения не проходит либо Mac недоступен | Проверить маршрут, DNS, прокси, питание и доступность |
| Ошибка сборки | Job стартовал и упал на команде или шаге | Исправить зависимости, права, скрипт или окружение проекта |
Решение по симптомам: исправить, обслуживать или сменить размещение
Самостоятельный Runner остаётся разумным выбором, если у команды есть доступ к Mac, понятная ответственность за обслуживание и время на диагностику обновлений, сети и службы. Удалённый Mac стоит рассматривать не как универсальный ремонт, а когда проблема подтверждённо связана с доступностью хоста, нестабильной средой или высокой нагрузкой на команду поддержки. Даже тогда переход потребует перенести и проверить конфигурацию workflow, секреты и зависимости.
| Условие | Что выбрать | Почему |
|---|---|---|
| Не совпадают метки или права | Исправить настройки текущего Runner | Замена хоста не меняет правила маршрутизации |
| Mac доступен, но launchd не стартует | Исправить службу и проверить повторно | Сначала нужно подтвердить причину отказа запуска |
| Регулярно недоступен сам хост или сеть | Оценить другую схему размещения Mac | Нужна инфраструктура, которую команда сможет поддерживать |
| Сбой воспроизводится внутри сборочного шага | Исправить проектное окружение | Перенос не устраняет ошибку скрипта или зависимостей |
Если рассматриваете облачную Mac-среду для постоянной работы Runner, сопоставьте требования проекта с описанием удалённого Mac, а срок использования и формат оплаты — с условиями аренды. Перед переносом проверьте, что ваша система сборки действительно работает в выбранном окружении; ошибка меток или YAML останется ошибкой конфигурации и на другом Mac.
Частые вопросы по macOS Runner
Что проверить первым, если GitHub Actions macOS Runner показывает офлайн?
Сначала подтвердите доступность Mac и состояние процесса, затем выполните сетевую проверку на самом хосте и изучите _diag. Не начинайте с повторной регистрации, пока не проверены DNS, прокси, исходящий доступ и доверие к сертификатам.
Почему macOS Runner онлайн, а workflow продолжает ждать?
Сверьте все метки из runs-on, состояние занятости и доступ группы к репозиторию. Для назначения задания недостаточно, чтобы исполнитель просто отображался онлайн: он должен соответствовать условиям маршрутизации и иметь нужные разрешения.
Как убедиться, что служба launchd работает после перезапуска?
Проверьте sudo ./svc.sh status из каталога Runner, затем сопоставьте состояние службы с журналами и отображением узла в GitHub Actions. Запуск из терминала не подтверждает автоматический старт и работу в контексте службы.
Где искать подробности, если Runner не подключается к GitHub?
Выполните ./config.sh --check, изучите диагностические файлы в _diag и проверьте журнал сетевого события в нужное время. Затем сопоставьте его с логом workflow: ошибка соединения и ошибка шага сборки требуют разных исправлений.
Когда нужен другой Mac
Если проверки указывают на ошибки меток, прав или сборочного скрипта, оставьте Runner на текущем хосте и исправьте подтверждённую причину. Но если Mac регулярно недоступен, служба требует постоянного ручного вмешательства, а команда не может обеспечить обслуживание узла, самостоятельная схема создаёт реальные издержки: дежурство за физической машиной, зависимость от её локальной сети и риск перерыва после сбоя или перезагрузки.
В таком случае аренда реального Mac у VPSPull может быть удобнее для команды, которой нужен удалённый доступ по SSH, VNC или веб-консоли и отдельная среда для CI. Это не освобождает от настройки Runner и workflow, поэтому сначала перенесите конфигурацию и проверьте её на тестовом запуске. Если же сборки идут постоянно с предсказуемой высокой нагрузкой или проекту необходимы физические интерфейсы и локальная периферия, собственный Mac может оставаться более подходящим вариантом.
Часто задаваемые вопросы
С чего начать, если самостоятельный macOS Runner отмечен как офлайн?
Сначала проверьте, включён ли Mac и запущен ли процесс Runner, затем выполните сетевую проверку из каталога установки и сопоставьте результат с журналами в `_diag`. Не начинайте с повторной регистрации: если мешает DNS, прокси, межсетевой экран или недоверенный сертификат, новая регистрация не устранит причину. Проверяйте соединение штатными средствами, не отключая TLS-проверку.
Почему задание остаётся в очереди, хотя macOS Runner отображается онлайн?
Статус онлайн сам по себе не означает, что исполнитель подходит конкретному workflow. Сверьте все значения `runs-on` с метками Runner, проверьте, что Runner свободен, и убедитесь, что его группа разрешена для репозитория или организации. Если настройки не совпадают, GitHub не направит задание на этот узел; менять Mac из-за ошибки маршрутизации не требуется.
Как проверить запуск Runner через launchd после перезагрузки Mac?
В каталоге Runner выполните `sudo ./svc.sh status` и отдельно проверьте доступность узла в настройках GitHub Actions. Если служба остановлена, изучите её регистрацию и журналы Runner, прежде чем запускать процесс вручную. Успешный запуск из интерактивного терминала подтверждает только работу в этой сессии, но не доказывает, что служба launchd стартует автоматически и сохраняет нужное окружение.
Какие журналы помогут при ошибке сетевого соединения Runner?
Сначала запустите штатную проверку соединения командой `./config.sh --check` из каталога установки; затем изучите файлы Runner в `_diag` и журналы конкретного workflow. Сопоставьте отметки времени и проверьте DNS, прокси, правила исходящих подключений и доверие к сертификатам. Если Runner подключается, но падает шаг сборки, ищите причину в workflow и выводе команды, а не только в сетевом журнале.
Читайте также
Перенесите Runner на выделенный Mac
VPSPull предоставляет физические компьютеры Apple Silicon, которые можно выделить под собственный Runner и сборки macOS.
