Как настроить Apple notarytool в корпоративном CI? Руководство по развёртыванию 2026

Apple notarytool можно встроить в корпоративный CI, если разделить сборку и подпись, отправку, проверку результата, обработку билета и финальную приёмку. На этой неделе возьмите один реальный артефакт выпуска и пройдите по нему весь маршрут: этапы, зависящие от Xcode или stapler, проверяйте в macOS, а Notary API рассматривайте только для замены части операций отправки и проверки состояния.

Кому подойдёт это руководство:

Командам, распространяющим macOS-приложения вне Mac App Store и включающим Developer ID и нотариальную проверку в выпуск.

ИТ-специалистам, отвечающим за CI, доступ к ключам и разделение полномочий, а также инженерам, принимающим решение о готовности релизного файла.

Подготовка: определите, что именно вы выпускаете

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

Составьте карту процесса до изменения CI:

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

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

Заранее разграничьте обязательные этапы и варианты реализации. notarytool предоставляет командный путь для управления потоком, проверки статуса и получения журнала; Notary API позволяет автоматизировать часть операций отправки и запроса статуса. API не подменяет саму сборку macOS-приложения и не отменяет этапы, для которых вам нужны Xcode или stapler. Актуальные варианты процесса описаны в документации Apple по настройке рабочего процесса нотариальной проверки.

Сборка: подпишите тот же артефакт, который пойдёт в выпуск

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

Перед отправкой проверьте применимые условия подписи:

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

Не считайте это универсальным списком требований для любого типа программы: критерии зависят от продукта и способа распространения. Условия Hardened Runtime и его настройки сверяйте с документацией Apple по Hardened Runtime, а требования к подписи и распространению — с документацией Developer ID.

Разработка и выпуск — разные контексты. Подпись, пригодная для внутреннего тестирования, сама по себе не подтверждает готовность пакета к распространению. Передайте в релизный поток окончательный объект, подписанный для нужного способа распространения, и сохраните доказательства того, какой именно файл был проверен. Если команда использует Xcode Organizer для ручного выпуска, зафиксируйте, какие проверки остаются на инженере; если нужна повторяемость, перенесите соответствующие действия в скриптируемый CI и контролируйте его входы и выходы.

Аутентификация: ограничьте задачу, которой доступны секреты

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

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

Не вставляйте секрет в скрипт как постоянную строку и не включайте подробный вывод команды до проверки его поведения. Замаскированное отображение переменной в CI не заменяет ограничения доступа к её источнику и проверку журналов.

Закрепите ответственность за выдачу, отзыв и замену учётных данных. При уходе сотрудника или изменении прав доступа выясните, какие задачи используют его ключ, и проверьте, что выпуск не зависит от персонального секрета без назначенного владельца. Храните журнал изменения доступа отдельно от журнала самой сборки, если это требуется вашим процессом контроля.

Отправка: сохраните идентификатор и дождитесь конечного состояния

Отправляйте на проверку тот упакованный объект, который соответствует выбранному способу распространения. Для notarytool организуйте получение результата как отдельный этап: CI должен сохранить идентификатор отправки, чтобы позднее запросить статус и связать ответ Apple с коммитом, заданием и артефактом. Командная справка и последовательность действий приведены в руководстве Apple по настройке рабочего процесса.

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

Если вы оцениваете Notary API, проверьте отдельно операции передачи программного обеспечения и запроса состояния. В описании отправки через Notary API и документации по отправке программного обеспечения описан API-путь; он может заменить часть командного взаимодействия, но не свидетельствует, что весь процесс сборки, подписи и обработки результата можно перенести за пределы Mac. Заранее проверьте требования API к аутентификации и соответствие выбранной схемы прав вашей организационной модели.

Частые вопросы на этапах сборки и отправки

Можно ли отправлять сборку с подписью для разработки?
Ориентируйтесь не на название конфигурации в CI, а на пригодность конкретной подписи и артефакта для предполагаемого распространения. Внутренний тестовый пакет не становится готовым релизом после успешной компиляции. Зафиксируйте сертификат, параметры подписи и состав пакета, а затем подтвердите их для фактического способа выпуска по документации Apple.

Что выбрать для выпуска: Xcode Organizer или сценарий CI?
Organizer подходит, если релиз пока проходит через контролируемую ручную операцию и вы способны сохранять её доказательства. Скриптированный CI уместнее, когда требуется воспроизводимая последовательность для команды. В обоих вариантах определите, кто проверяет итоговый статус, хранит журнал и обрабатывает билет: автоматизация команды не отменяет ответственность за приёмку.

Как не раскрыть данные доступа в CI?
Храните их в системе управления секретами, выдавайте только тем заданиям, которым они действительно нужны, и исключите вывод чувствительных значений. Не записывайте учётные данные в исходный сценарий, параметры артефакта или журнал. Документируйте владельца ключа, разрешённые задачи и порядок отзыва; конкретный формат настройки выбирайте по документации Apple для применяемой схемы.

Что делать с результатом Invalid?
Сначала получите подробный журнал по идентификатору отправки и проверьте, что журнал относится к тому же файлу, который собирается выпустить CI. Затем разберите сообщения о подписи, вложенных компонентах, Hardened Runtime или структуре упаковки. Исправление должно пройти через сборку заново, чтобы в истории сохранилась связь между источником, подписанным объектом и повторной отправкой.

Когда Notary API действительно заменяет команду?
Только в ограниченной части процесса, которую покрывает API, например при отправке и последующей проверке состояния. Сборка, использование Xcode и применимые операции stapler остаются отдельными этапами. Если задача зависит от этих инструментов, проверьте её на macOS и не переносите вывод о замене одной операции на весь Mac CI.

Результат: обработайте билет и проверьте объект выпуска

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

Далее определите, требуется ли для выбранного формата прикрепить билет и каким именно способом это сделать. В подходящем сценарии stapler применяется к поддерживаемому объекту, после чего необходимо проверить уже обработанный файл. Формат имеет значение: к ZIP нельзя напрямую прикрепить билет; если доставка оформлена ZIP-архивом, планируйте шаги с учётом вложенного поддерживаемого объекта, а не рассчитывайте на stapling самого архива. Подтверждайте этот выбор по актуальным инструкциям Apple и проверяйте конечный объект, предназначенный пользователю.

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

Выпуск: выберите среду по этапам, а не по названию API

Для решения о размещении CI разделите сценарий на операции, требующие Mac, и операции, которые можно отдельно оценить для API-автоматизации. Ниже — условия выбора; формулировки «высокая», «условная» и «низкая» — оценка применимости для описанного сценария, а не гарантия Apple или оценка конкретного поставщика.

• Если сборка использует Xcode, подписание или stapler, выбирайте среду macOS для этих этапов и проверяйте весь поток на реальном выпускном артефакте. Иначе вернитесь к проектированию CI: API не заменяет отсутствующие инструменты сборки.
• Если сборка и подпись уже проходят на Mac, а узкое место — автоматизация отправки и запроса состояния, оцените Notary API как замену соответствующей части notarytool. Сначала подтвердите аутентификацию, обработку ответов и сохранение идентификаторов; если эти условия не закрыты, оставьте командный маршрут.
• Если команда публикует только через Mac App Store, не переносите на него без проверки тот же процесс распространения вне магазина. Сначала подтвердите фактическую модель выпуска и применимые требования.
• Если нет владельца секретов, журнала и финального решения о выпуске, не включайте автоматическую публикацию только на основании успешной сборки. Сначала назначьте ответственных и оформите критерии остановки.

Сопоставление вариантов помогает не покупать лишнюю инфраструктуру и не делать выводов о среде по одной операции:

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

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

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