Как автоматически архивировать артефакты сборки Xcode Cloud? Руководство 2026

Автоматически архивируйте нужные артефакты Xcode Cloud сразу после завершения сборки: скачайте их через Xcode, App Store Connect или API, проверьте файлы и сохраните в своём хранилище. Это подходит командам, которым важно восстановить контекст сбоя, подтвердить результаты тестирования или повторно проверить выпуск после того, как материалы перестанут быть доступны в облаке Apple.

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

Сначала определите, что именно нужно сохранить

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

В документации Apple указано, что информация о сборках Xcode Cloud и связанные артефакты доступны не более тридцати дней. Это срок облачной доступности материалов, а не правило для срока хранения в хранилище команды. Если они понадобятся позднее, их нужно скачать заранее. Apple описывает доступные материалы и способы их сохранения в документации Xcode Cloud.

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

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

Пока автоматизация не готова, скачивайте материалы вручную

Ручной способ подходит для редких сборок, первичной проверки состава артефактов или процесса, в котором специалист должен подтвердить файлы перед сохранением. Откройте отчёт сборки в Xcode либо найдите нужную сборку в App Store Connect. Перейдите к действиям сборки, просмотрите доступные материалы и скачайте только то, что требуется для вашей задачи.

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

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

Затем свяжите сборку с её действиями и артефактами

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

На этом этапе не привязывайте обработку к предположению, что в каждом ответе будет одинаковое число файлов или одинаковые типы. Разберите структуру ответа API, выберите нужные ресурсы по их атрибутам и сохраните исходную связь с действием сборки. Описание атрибутов артефакта CI и запрос сведений об отдельном артефакте используйте как источник актуальных имён и значений полей.

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

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

Настройте авторизацию и скачивание как единый процесс

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

Рабочий процесс должен выполнять несколько действий последовательно:

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

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

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

Проверьте результат и закрепите правила хранения

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

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

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

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

Контроль перед включением процесса в постоянную работу:

• [ ] Состав архива соответствует задаче: публикация, диагностика или проверка тестов.
• [ ] Сборка связана с рабочим процессом, действием и исходным коммитом.
• [ ] API-ключ и приватный ключ доступны только автоматизации, которой они необходимы.
• [ ] Скрипт получает актуальные сведения об артефакте перед каждой загрузкой.
• [ ] Ошибка одного файла не маскируется как успешное сохранение всего набора.
• [ ] Загруженные материалы открываются и соответствуют ожидаемому типу.
• [ ] Доступ к архиву ограничен, а журнал не раскрывает JWT и другие секреты.
• [ ] Назначены ответственный за хранение и владелец правил очистки.

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

Как долго доступны сборки и артефакты Xcode Cloud?
Apple указывает, что сведения о сборке и её артефакты доступны в Xcode Cloud не более тридцати дней. Это срок облачной доступности у Apple, а не готовая политика хранения команды. Если сборка нужна для расследования сбоя, повторной проверки или подтверждения выпуска позднее, загрузите нужные файлы и сохраните их в собственном хранилище до истечения этого срока.

Как скачать артефакты Xcode Cloud через App Store Connect API?
Сначала получите авторизованный доступ к App Store Connect API, затем найдите нужную сборку и действие сборки, запросите список связанных артефактов и сведения о выбранном файле. Из ответа возьмите актуальный адрес загрузки, скачайте файл сразу и сохраните метаданные сборки рядом с ним. Названия полей и доступные ресурсы сверяйте с текущей схемой Apple.

Как сохранить журналы сборки и результаты тестирования Xcode Cloud?
Определите, какие именно материалы нужны для расследования: журнал, результат тестирования, архив приложения или символы. Найдите их в отчёте сборки либо через API, скачайте и проверьте каждый файл. Храните их вместе с идентификатором сборки, ссылкой на коммит и сведениями о рабочем процессе. Доступ к журналам ограничьте, если они могут содержать внутренние данные.

Можно ли постоянно использовать ссылку на скачивание артефакта из API?
Нет. Ссылка из ответа API предназначена для загрузки и действует ограниченное время, поэтому её нельзя считать постоянным местом хранения или записывать как ссылку на архив. Автоматизация должна получить адрес, скачать файл и проверить результат в рамках одного процесса. В архиве сохраняйте сам файл и необходимые метаданные, но не полагайтесь на временный URL.

Если текущий процесс опирается только на облачную доступность Xcode Cloud, у него есть три практических ограничения: ограниченный срок доступа к материалам, временные ссылки загрузки и необходимость самостоятельно связать файлы с коммитом и результатами проверки. Отдельная среда Mac не заменит хранилище и не отменит эту работу, но может пригодиться для постобработки или проверки архива средствами macOS. Когда такой этап нужен временно, аренда Mac у metalvnc может быть удобнее покупки отдельной машины; если же требуется постоянная высокая нагрузка или физические интерфейсы, сначала оцените локальный Mac. Сравнить условия можно на странице тарифов metalvnc.

Часто задаваемые вопросы