В этой проверке удобно разделить сбой на три границы: настройки проекта, среда выполнения Runner и материалы подписи. Это диагностическая схема, а не гарантия причины: документация Apple по сборке и запуску приложений описывает этапы сборки, а руководство GitHub по поиску неисправностей self-hosted Runner — проверку его работы и журналов. При сбое подписи Xcode в GitHub Actions сначала установите, под какой учётной записью фактически работает Runner и доступен ли этой учётной записи macOS Keychain; затем проверьте identity и соответствующий профиль. Успешная подпись в SSH-сеансе сама по себе не доказывает, что CI видит те же материалы.
Кому пригодится это руководство
Разработчикам iOS и macOS — если локальная сборка подписывается, а в Workflow не проходит архивирование или подпись.
Инженерам DevOps — если нужно воспроизводимо установить пользователя и окружение self-hosted Mac Runner.
Релизным инженерам и администраторам секретов — если требуется отличить проблему сертификата от проблемы закрытого ключа, Keychain или профиля и не раскрыть производственные данные лишним задачам.
[ SECTION_01 ] Разделите ответственность до изменения сертификатов
Не считайте любую ошибку подписи признаком испорченного сертификата. Ошибка может возникнуть до выбора identity, при доступе процесса к закрытому ключу или при несовпадении профиля с целевым приложением. Сначала сохраните ссылку на неудачный запуск и сопоставьте его с локальной сборкой на том же коммите и с тем же целевым Scheme.
| Этап | Что проверить | Доказательство для передачи следующему ответственному |
|---|---|---|
| Сборка и архивирование | Команда, Scheme, Target и параметры, использованные Workflow | Фрагмент лога с фактическими параметрами и последним успешно завершённым этапом |
| Выбор подписи | Настройки signing и выбранная identity | Build settings и сообщение Xcode о выборе или поиске identity |
| Доступ к ключу | Пользователь процесса Runner и состояние Keychain | Проверка из самого Workflow, а не только из SSH-терминала |
| Соответствие профиля | Идентификатор приложения, команда и назначение профиля | Данные конфигурации проекта и профиль, выбранный для целевой сборки |
Для проверки параметров сборки используйте справочник настроек Xcode. Он помогает отделить заданные проектом значения от предположений, основанных на том, как обычно настроена рабочая машина. Зафиксируйте Bundle Identifier, Team ID, Scheme и режим подписи как заполнители в отчёте; реальные секреты и содержимое закрытого ключа в логи не помещайте.
Удобно оценивать свидетельства по простой шкале: 0 — проверка не выполнена или её результат неизвестен; 1 — результат получен внутри того же Workflow и сохранён в логе. Оценка «1» означает только наличие проверяемого свидетельства, а не то, что настройка правильная. Если по пункту стоит «0», передавайте задачу владельцу соответствующего слоя, не меняя остальные настройки наугад.
[ SECTION_02 ] Разработчик: почему локальная подпись может не повториться в CI?
На локальном Mac и в CI могут отличаться Scheme, Target, параметры xcodebuild, выбранный способ подписи и значения, заданные через переменные окружения. Внешне одинаковая команда не обязательно означает одинаковую конфигурацию: параметры Workflow могут переопределять значения проекта. Поэтому сравнивайте не только файл проекта, но и фактические параметры из журнала задания.
Проверьте, что локальная и CI-сборка используют один и тот же коммит, один и тот же целевой Scheme и одно назначение — например, архив для ожидаемого канала распространения. Не смешивайте автоматическое управление подписью с вручную заданным выбором профиля и сертификата. Если один вариант работает локально, а Workflow запускает другой, сначала устраните расхождение конфигурации.
Затем сверьте связанные значения:
- Bundle Identifier должен относиться к собираемому приложению, а не к другому Target.
- Team ID должен совпадать с командой, для которой выпущены используемые материалы.
- Профиль должен соответствовать приложению и сценарию распространения.
- Настройки Scheme и Target должны вести к той же стратегии подписи, которая предполагается в CI.
Документация Apple по созданию профиля App Store объясняет назначение профиля и сведения, с которыми его следует соотносить. Если идентификатор приложения, команда или назначение профиля не совпадают, повторный импорт того же файла в Keychain не исправит несоответствие. Передайте администратору подписи конкретные значения из конфигурации и лога, а не общее описание «сертификат не работает».
[ SECTION_03 ] Инженер DevOps: почему SSH-сеанс и Runner видят разные Keychain?
Частая причина расхождения — сравнение интерактивной оболочки с процессом GitHub Actions. SSH-подключение может выполняться от одной учётной записи, а служба Runner — от другой. Тогда успешная проверка в терминале говорит только о доступе текущего SSH-пользователя; она не подтверждает права процесса Workflow.
Установите фактическую учётную запись, от имени которой выполняется задание. Смотрите контекст самого Workflow, сведения о процессе Runner и его журналы. Если Runner запущен как служба через launchd, отдельно проверьте состояние этой службы и сопоставьте его с логами. Документация GitHub по настройке приложения self-hosted Runner и инструкции по диагностике Runner помогают выяснить, как он настроен и где искать признаки проблем в работе службы.
| Наблюдение | Что оно подтверждает | Чего оно не подтверждает |
|---|---|---|
| Подпись проходит в SSH-терминале | Текущий интерактивный пользователь может выполнить проверку в своём контексте | Что служба Runner работает от того же пользователя и видит тот же Keychain |
| Workflow находит сертификат в списке | В его контексте обнаружена запись сертификата | Что соответствующий закрытый ключ доступен для операции подписи |
| Runner отмечен как работающий | Узел доступен для выполнения заданий | Что конкретный Workflow получил нужные права и корректные signing assets |
| Сборка завершилась | Сборочный этап прошёл | Что созданный архив подписан для нужного сценария и готов к выпуску |
Как установить пользователя и Keychain, доступные GitHub Actions?
Добавьте в контролируемую диагностическую задачу проверки контекста процесса: определение текущего пользователя, проверку ожидаемой связки Keychain и безопасную проверку наличия нужной identity. Выполняйте их именно внутри Workflow и записывайте только необходимую диагностическую информацию. Не выводите пароли Keychain, закрытые ключи, содержимое секретов или файлы профилей целиком.
Затем сравните вывод с тем, что получает SSH-пользователь, и с параметрами службы Runner. Для macOS Keychain важен не только факт наличия записи, но и доступность её закрытого ключа для фактического процесса. Если результаты в SSH и Workflow различаются, сначала разберите пользователя, запуск службы и выбранную связку Keychain. Не начинайте с повторного импорта сертификатов: это может добавить дубликаты, но не изменить контекст, в котором работает CI.
[ SECTION_04 ] Администратор подписи: identity найдена, но Xcode всё ещё отказывает
Наличие сертификата в списке — не то же самое, что возможность подписывать. Кодовая identity должна быть пригодна для требуемой операции, а соответствующий закрытый ключ — доступен процессу. Документация Apple об identity описывает identity как связанный материал подписи; техническая заметка Apple о сертификатах кодовой подписи помогает разбирать роль сертификата и доверенной цепочки.
Проверяйте identity из того же окружения, где работает Workflow. Системную команду security find-identity -v -p codesigning можно использовать как один из способов получить сведения о найденных signing identity, но её результат не заменяет проверку доступности закрытого ключа при реальной сборке. Сопоставьте выбранную identity с тем, что сообщает Xcode в журнале. Не публикуйте полный вывод без предварительной проверки: имена и сведения об организации могут раскрывать внутреннюю информацию.
Далее проверьте профиль отдельно от Keychain. Сопоставьте его назначение, идентификатор приложения и Team ID с фактическим Target. Если identity доступна, но профиль относится к другому приложению или другому сценарию, исправлять нужно комплект подписи или настройки проекта, а не права Keychain. Записывайте изменения: какой материал заменён, кто одобрил обновление, как вернуть прежнее состояние. Это позволяет восстановить работающую конфигурацию, если новая связка не пройдёт архивирование.
Не расширяйте доступ к Keychain и секретам лишь ради устранения ошибки. Сначала докажите, какой процесс не получает доступ, к какому материалу и почему. Временное расширение прав без установленного владельца риска превращает локальную диагностику в проблему безопасности.
[ SECTION_05 ] Владелец репозитория и специалист по безопасности: ограничьте доступ к подписи
Подписывающий Workflow обрабатывает материалы, которые могут дать возможность выпускать приложение от имени команды. Поэтому важно проверить не только корректность сборки, но и то, какие репозитории, события, сотрудники и задания могут запустить её. В частности, не следует автоматически предоставлять недоверенному заданию доступ к производственным секретам или к общему Runner, где эти материалы доступны.
Руководство GitHub по безопасному использованию GitHub Actions описывает риски, связанные с Workflow и доступом к секретам. На практике зафиксируйте в политике команды, какие события допускаются к подписывающим заданиям, какие репозитории могут направлять задачи на Runner и кто утверждает изменения в таком процессе. Доступ к учётным данным должен быть ограничен именно теми заданиями, которым он необходим.
Если для диагностики требуется временно изменить права или маршрут задания, оформите изменение с владельцем, обоснованием, областью действия и способом отката. Сначала отделите задачу подписи от недоверенной сборочной активности или направьте её на отдельный узел, если текущую границу доступа нельзя надёжно проверить. Не отключайте защитные проверки ради зелёного статуса: такой статус не доказывает, что выпускной контур остался безопасным.
[ SECTION_06 ] Пошаговая проверка перед повторным запуском
Используйте список как последовательность передачи ответственности. Переходите дальше только после того, как результат текущей проверки сохранён и понятен следующему владельцу.
- [ ] Зафиксируйте неудачный запуск, коммит, Scheme, Target и цель сборки. Убедитесь, что локальное сравнение выполнено на том же коммите.
- [ ] Найдите в логе последний успешно завершённый этап. Отделите ошибку сборки или архивации от сообщения о выборе identity, доступе к ключу или проверке профиля.
- [ ] Сверьте фактические параметры Workflow с настройками проекта и целями подписи. Если значения расходятся, передайте разработчику точные названия параметров и источники их переопределения.
- [ ] Проверьте учётную запись процесса Runner и его состояние. Сопоставьте результаты из Workflow, службы Runner и SSH-сеанса; не считайте их взаимозаменяемыми.
- [ ] Проверьте macOS Keychain и signing identity в контексте Workflow. Подтвердите отдельно наличие сертификата и доступность соответствующего закрытого ключа.
- [ ] Сверьте профиль с Bundle Identifier, Team ID и назначением выпуска. Если есть несовпадение, передайте администратору подписи конкретные значения и не меняйте права Keychain вместо профиля.
- [ ] Проверьте, какие репозитории и события могут запускать задачу с доступом к материалам подписи. Согласуйте нужные ограничения и документируйте временные исключения.
- [ ] Запустите чистый Workflow для фактической цели распространения. Проверьте не только завершение сборки, но и подпись архива и ожидаемые свойства итогового артефакта.
- [ ] Сохраните результат и зафиксируйте, какие изменения исправили проблему. Если контекст Runner остаётся нестабильным, изолируйте задание подписи до возвращения его в производственный выпуск.
[ SECTION_07 ] Релизный инженер: принимайте исправление по архиву
Онлайн-состояние Runner и успешная компиляция — недостаточные критерии приёмки. Повторный тест должен выполнять тот же целевой Workflow, который используется для выпуска, и создавать архив в ожидаемом контексте. Сверьте журнал, выбранную identity, результат подписи и свойства самого артефакта. Если проверен только тестовый Target, вывод нельзя автоматически переносить на выпускной Target.
Для повторяемости сохраните описание условий без секретов: коммит, выбранный Scheme и Target, тип запуска Runner, ожидаемую identity и тип профиля. После исправления запустите чистое задание, а не полагайтесь лишь на результат интерактивного терминала или состояние старого процесса. При провале передавайте следующему ответственному именно новый лог и установленное расхождение. Не удаляйте старые материалы до подтверждения, что новая связка работает и существует понятный путь возврата.
Если одну и ту же проблему нельзя объяснить стабильным контекстом выполнения, приостановите использование узла для производственной подписи. Сначала ограничьте маршрут подписывающих задач или восстановите специализированную среду, затем повторите проверку по той же процедуре. Это безопаснее, чем последовательно импортировать новые сертификаты, менять права и терять возможность понять, какое действие повлияло на результат.
[ SECTION_08 ] Когда имеет смысл сменить саму среду Runner
Если причина действительно в нестабильном или неподконтрольном исполнении, повторение тех же проверок на общем узле не создаст надёжную базу для выпуска. Локальная машина удобна для разработки, но может быть выключена, занята интерактивными задачами или настроена иначе, чем CI. Универсальный Linux-сервер, в свою очередь, не заменяет среду macOS для Xcode-процесса подписи и архивирования.
Для временной миграции, изолированного теста или восстановления выпуска удалённый Mac может дать отдельную macOS-среду, доступную для настройки Runner и проверки подписи. В каталоге NOVAKVM можно ознакомиться с доступными вариантами удалённого доступа к Mac, а страница заказа Mac mini пригодится, если уже принято решение использовать такой узел.
Выбор зависит от режима работы. Если подпись выполняется постоянно и требует физической периферии, длительной локальной эксплуатации или специальных сетевых ограничений, собственный Mac может быть практичнее аренды. Если же нужен временный CI-узел, воспроизводимая проверка или дополнительная среда на период миграции, аренда Mac у NOVAKVM позволяет оценить сценарий без немедленной покупки оборудования. При этом безопасность по-прежнему задают изоляция заданий, доступ к секретам и корректная настройка самого Workflow — удалённый Mac не заменяет эти меры.