Как устранить сбой CI при нотариальном заверении Apple? Руководство по исправлению 2026

При разборе сбоя CI при нотариальном заверении Apple прежде всего установите, какое событие действительно завершилось успешно. Передача файла, принятие запроса сервисом, завершение обработки с положительным результатом, прикрепление билета и проверка готового файла — самостоятельные этапы. Поэтому зелёный шаг загрузки не даёт основания допускать сборку к распространению.

Apple описывает нотариальное заверение macOS-программ перед распространением, включая допустимые типы файлов и общий ход процесса. Отдельно документированы отправка через Notary API, проверка статуса и получение журнала. Начните с описания нотариального заверения macOS-программ и документации о статусе отправки и журналах Notary API.

В вывод CI добавьте сохранение следующих данных:

• идентификатора отправки, возвращённого инструментом или API;
• полного ответа о статусе, а не только сообщения «загрузка успешна»;
• журнала обработки, если он доступен;
• кода завершения и вывода команды отправки;
• пути и контрольной идентичности конечного артефакта, чтобы сопоставить журнал именно с файлом релиза.

Если идентификатор не сохранился, запрос был прерван или журнал пока недоступен, не делайте вывод, что Apple отклонила подпись. Сначала выясните, существует ли отправка и завершилась ли её обработка. До подтверждённого результата сборка должна оставаться вне релизного канала. Это правило применимо и к локальному агенту, и к удалённому Mac, и к другой системе оркестрации.

Для операций с notarytool сохраните команду, параметры аутентификации без секрета и ответ сервиса. Не записывайте пароль, приватный ключ или токен в открытый лог. В руководстве Apple по автоматизации нотариального заверения сверяйте актуальное описание рабочего процесса, а порядок проверки статуса и получения журнала — с документацией Notary API.

Слово «подпись» может относиться к разным проверкам. Подпись приложения Developer ID, подпись установочного пакета и учётные данные, которыми автоматизация обращается к службе заверения, не взаимозаменяемы. Ошибка аутентификации отправки не доказывает, что приложение подписано неверно; сообщение о проблеме подписи не означает автоматически, что неисправен Mac-узел.

При анализе разделите проверки на три направления:

• Подписан ли конечный код способом, предусмотренным для распространения? Установите, какой объект проверял сервис: приложение, установочный пакет или другой файл.
• Может ли задача CI получить нужное полномочие? Проверьте выбранную учётную запись и доступ процесса сборки к требуемым учётным данным, не выводя секреты в журнал.
• Может ли отправка пройти аутентификацию? Сопоставьте используемый способ входа и сохранённую конфигурацию с фактическим ответом сервиса.

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

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

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

Следуйте замечаниям в официальном журнале и устанавливайте, к какому компоненту они относятся. Проверьте, совпадает ли отправленный объект с файлом релиза, сохранена ли ожидаемая структура, нет ли внутри компонента с отдельной ошибкой подписи и соответствуют ли entitlements фактической сборке. Apple разбирает типовые проблемы в справке по устранению ошибок нотариального заверения; требования к подготовке Mac-программы для распространения собраны в руководстве по упаковке программ.

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

Учитывайте целевой формат. Не переносите автоматически один и тот же набор действий на приложение, установочный пакет и архив: применимый путь зависит от того, что подготовлено к выпуску. Если запись CI указывает на промежуточный продукт, сначала исправьте выбор входного файла, а затем повторите отправку. Это не обязательно требует повторной компиляции исходного кода, но после изменения упаковки нужно заново проверить именно сформированный для релиза файл.

Используйте этот список как инструмент решения: отметьте условия, подтвердите причину по ответу сервиса или журналу и меняйте только относящуюся к ней часть процесса.

• [ ] Если отправка не прошла аутентификацию или передача не завершилась, проверьте учётные данные, параметры запроса, сетевой выход и доступ CI-агента. Если запрос мог быть принят до обрыва соединения, сначала установите его статус. Не пересобирайте приложение из-за сетевой ошибки.
• [ ] Если запрос принят, но итог обработки ещё не подтверждён, сохраните идентификатор и запросите статус повторно. Не считайте незавершённое состояние отказом и не запускайте новую отправку, пока не выяснено, что произошло с предыдущей.
• [ ] Если журнал указывает на подпись или entitlements, исправьте этап подписи или настройки прав для затронутого компонента. Заново сформируйте конечный файл и проверьте его до отправки. Не меняйте настройки узла, если журнал не связывает их с причиной.
• [ ] Если причина связана со структурой или упаковкой, исправьте подготовку дистрибутива и проверьте новый конечный артефакт. Повторно подписывать неизменённое приложение без свидетельства ошибки подписи не требуется.
• [ ] Если заверение принято, но проверка распространения не проходит, перейдите к прикреплению билета и проверке готового файла. Не отправляйте тот же файл повторно, пока не установлено, что проблема именно в результате заверения.
• [ ] Если журнал не объясняет отказ, сохраните идентификатор, полный статус и официальный журнал, проверьте системное состояние служб разработчика и эскалируйте проблему с этими данными. Не приписывайте сбой инфраструктуре CI без подтверждения.

Для неинформативного сообщения сохраните вывод команды и ответ сервиса целиком. Проверьте системный статус служб разработчика на странице состояния Apple. Если страница не подтверждает сбой, а журнал не даёт объяснения, изолируйте воспроизводимый артефакт и передавайте в эскалацию собранные свидетельства. Не предполагайте фиксированное время обработки: ориентируйтесь на фактическое состояние отправки и доступность журнала.

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

Что проверять, если notarytool завершил отправку, но статус отрицательный?

Сохраните идентификатор отправки и получите статус вместе с журналом. Успешная передача файла не означает, что Apple приняла результат обработки. Найдите в журнале объект и описание проблемы, затем сопоставьте их с конечным приложением или пакетом. После исправления отправляйте новый артефакт; повторять ту же операцию без выяснения причины — значит рисковать потерей диагностического контекста.

Как понять по логу Apple, связана ли ошибка с подписью?

Смотрите на конкретный этап и затронутый компонент. Ошибка учётных данных или отправки относится к обращению CI к службе, тогда как замечания к подписи или entitlements относятся к проверяемому коду и должны подтверждаться записью о соответствующем объекте. Сверьте формулировку с официальной справкой Apple, затем проверьте тот же конечный файл, который попал в отправку.

Нужно ли прикреплять билет после положительного результата?

Положительный итог нотариального заверения сам по себе не подтверждает, что билет прикреплён к распространяемому файлу. Для поддерживаемого формата выполните предусмотренную Apple операцию с помощью stapler, затем проверьте результат на конечном артефакте. Сохраните вывод обеих проверок в CI. Сначала убедитесь, что формат приложения подходит для выбранного действия, сверившись с документацией Apple по заверению и упаковке.

Как выбрать между повторной подписью, новой отправкой и исправлением упаковки?

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

Положительный ответ службы — не единственное свидетельство готовности выпуска. При приёмке Mac CI сохраните единый набор данных, по которому другой инженер сможет восстановить, что именно было проверено и какой файл получил допуск:

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

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

Для команд, которые распределяют ответственность между платформенной группой и безопасностью, зафиксируйте, кто управляет учётной записью CI и связкой ключей, кто утверждает изменение подписи, а кто принимает итоговый артефакт. Это снижает риск, что при отказе инженер начнёт менять защищённые учётные данные без подтверждения связи с причиной. Для проверки обращений и условий использования удалённого Mac доступны раздел помощи NUKCLOUD и условия сервиса.

Если проблема оказалась не в проекте, а в доступности постоянного CI-узла или его учётной среде, для краткосрочной диагностики может быть удобнее отдельный удалённый Mac, чем покупка дополнительной машины и её дальнейшее обслуживание. Собственный Mac остаётся разумным выбором при длительной постоянной нагрузке, строгой зависимости от физического интерфейса или особых требованиях к внутренней сети. Удалённая аренда не отменяет проверку ключей, прав и конечного файла, но позволяет испытать процесс на отдельной среде без немедленного расширения парка оборудования. Доступные варианты аренды Mac у NUKCLOUD указаны на странице тарифов; перед переносом выпуска проверьте на реальной задаче весь путь от подписи до проверки конечного файла.