Автоматическая сборка в fastlane: удалённый Mac в 2026

С 2026 года для загрузки приложений в App Store Connect требуется Xcode 14 или новее — это прямо указано в официальной таблице поддерживаемых версий загрузки. Поэтому действуйте по расписанию: в первый час зафиксируйте macOS, Xcode и fastlane, в первый день отдельно проверьте сборку и подпись, а в течение первой недели доведите процесс до воспроизводимой загрузки в TestFlight. Не включайте автоматическую отправку на проверку, пока четыре этапа — сборка, подпись, загрузка и восстановление секретов — не проходят независимо.

Эта инструкция предназначена для вас, если вы разрабатываете на Windows или Linux и не имеете локального Mac, уже публиковали приложение вручную, но регулярно сталкиваетесь с сертификатами и Provisioning Profile, либо хотите превратить удалённый Mac в постоянно работающий iOS-сборочный сервер.

Сначала разделите публикацию на проверяемые этапы

Ошибка «архив создан, но загрузка не завершилась» показывает, почему простая установка fastlane ещё не является автоматизацией релиза. Успешный Archive означает только, что Xcode смог собрать проект и подготовить архив. Это не доказывает, что:

• сертификат соответствует нужному Bundle ID;
• Provisioning Profile подходит для выбранного способа распространения;
• созданный .ipa связан с правильной версией приложения;
• App Store Connect принял файл и завершил его обработку;
• сервер сможет повторить операцию после перезапуска.

Разделите процесс на пять независимых состояний:

1. зависимости и исходный код установлены;
2. подпись и Archive завершены;
3. экспортирован ожидаемый .ipa;
4. файл принят и появился после обработки в TestFlight;
5. секреты и окружение можно восстановить на чистой сессии.

Apple указывает, что первое загруженное приложение должно быть заранее представлено записью в App Store Connect, а Bundle ID и номер версии внутри приложения используются для связывания сборки с записью версии. Обработка файла происходит уже после загрузки, поэтому момент завершения команды fastlane не равен моменту появления сборки в TestFlight. Подробная последовательность описана в документации Apple по загрузке сборок.

Подготовка удалённого Mac и прав доступа

Удалённый Mac должен рассматриваться не как временный рабочий стол, а как отдельная машина выпуска. Перед настройкой проверьте:

• версию macOS, которую поддерживает выбранный Xcode;
• установленный SDK и минимальную версию iOS, для которой вы собираете приложение;
• наличие командных инструментов Xcode;
• свободное место для Derived Data, Archive, .ipa и логов;
• часовой пояс, локаль и права пользователя, под которым будет запускаться задача.

На момент подготовки этой статьи стабильная строка Xcode 26.6 требует macOS Tahoe 26.2 или новее, а таблица Apple отдельно показывает поддерживаемые SDK, deployment target, Simulator и версии Swift. Если ваш проект ещё не готов к такой среде, не обновляйте машину вслепую: сначала сверьте проект с официальными системными требованиями Xcode.

Для удалённой работы используйте три канала с разными задачами:

• SSH — установка зависимостей, запуск Lane, получение логов и автоматизация;
• графическая консоль — первый вход в Xcode, принятие лицензии, проверка аккаунта и ручной просмотр Keychain;
• root-доступ — диагностика диска, системных служб и восстановления среды, но не хранение API Key в открытом каталоге.

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

До установки fastlane также проверьте в App Store Connect:

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

Для загрузки подходят роли Account Holder, Admin, App Manager и Developer, однако доступ к сертификатам и профилям регулируется отдельно. Поэтому разрешение на загрузку не означает автоматического доступа ко всем объектам подписи. Список ролей и ограничений следует сверять с официальными правилами управления сборками App Store Connect.

Первая настройка fastlane с фиксированными зависимостями

Для удалённого Mac не стоит полагаться на глобально установленную версию fastlane. Используйте Bundler и фиксируйте Gemfile.lock, чтобы разные запуски применяли одинаковый набор Ruby-зависимостей. Такой подход также упрощает восстановление после переустановки машины.

В корне проекта создайте Gemfile:

source "https://rubygems.org"

gem "fastlane"

Затем выполните:

bundle install
bundle exec fastlane init

В репозитории должны находиться:

Gemfile
Gemfile.lock
fastlane/Appfile
fastlane/Fastfile

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

В Appfile проверьте идентификатор приложения:

app_identifier("com.example.placeholder")
apple_id("developer@example.invalid")
team_id("TEAMID12345")

Замените значения на собственные только в локальной защищённой среде. В статье намеренно используются явные заполнители, а не реальные идентификаторы.

Первую Lane сделайте диагностической. Она должна только собрать проект и сохранить результат:

default_platform(:ios)

platform :ios do
  lane :build_only do
    build_app(
      workspace: "Example.xcworkspace",
      scheme: "Example",
      configuration: "Release",
      clean: true,
      output_directory: "build",
      output_name: "Example.ipa",
      buildlog_path: "build/logs"
    )
  end
end

Если у вас нет .xcworkspace, используйте project. Не угадывайте scheme: он должен существовать в проекте и быть доступен для совместного использования. Команда build_app создаёт Archive, выполняет экспорт и возвращает путь к итоговому .ipa; параметры workspace, scheme, configuration, archive_path и buildlog_path перечислены в справочнике fastlane для build_app.

Запуск:

bundle exec fastlane build_only 2>&1 | tee build/first-build.log

До перехода к подписи зафиксируйте:

• commit проекта;
• путь к активному Xcode;
• название scheme;
• номер версии и build number;
• полный лог команды;
• фактический путь к Archive и .ipa.

Подпись: автоматический режим или match

Когда подходит автоматическая подпись Xcode

Для одного разработчика и небольшого проекта можно начать с автоматического управления подписью в Xcode. Такой путь удобен, если вы готовы один раз войти в аккаунт разработчика через графическую сессию и не меняете часто набор target, capability и Bundle ID.

Проверяйте не только главный target. В проекте могут быть отдельные идентификаторы для:

• основного приложения;
• расширения Share или Notification Service;
• виджета;
• watchOS-компонента;
• тестового target.

Если один дополнительный target не имеет профиля, Archive может завершиться ошибкой уже после успешной компиляции исходников.

Когда лучше использовать match

Для постоянного удалённого Mac, нескольких окружений и команды предпочтительнее match. Он синхронизирует сертификаты и профили из выбранного защищённого хранилища, а в CI-режиме рекомендуется использовать режим readonly, чтобы задача не создавала и не отзывала подписывающие активы без участия человека. Условия и параметры приведены в официальной документации fastlane по match.

Первичная настройка выполняется вручную:

bundle exec fastlane match init

После сохранения существующих сертификатов рабочая Lane может выглядеть так:

lane :build_signed do
  match(
    type: "appstore",
    readonly: true,
    app_identifier: ["com.example.placeholder"]
  )

  build_app(
    workspace: "Example.xcworkspace",
    scheme: "Example",
    configuration: "Release",
    clean: true,
    output_directory: "build",
    output_name: "Example.ipa"
  )
end

Выбирайте match, если машина должна пережить перезапуск без ручного создания профилей. Оставляйте автоматическую подпись Xcode, если проект один, вы редко выпускаете обновления и хотите минимальное число сущностей для поддержки. В обоих случаях считайте этап пройденным только после проверки сертификата, Bundle ID, версии и профиля внутри результата.

Первый TestFlight: API Key отдельно от исходного кода

Безопасное хранение App Store Connect API Key

Для автоматической загрузки используйте API Key, а не пароль Apple Account. Ключ состоит из идентификатора ключа, Issuer ID и приватного файла .p8; роль ключа определяет доступ к операциям App Store Connect. Приватный ключ можно скачать только один раз, его нельзя хранить в репозитории, а при компрометации необходимо немедленно отозвать. Разъяснения по созданию и ограничениям ключей приведены в документации Apple по API Key.

На сервере храните .p8:

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

Не вставляйте содержимое приватного ключа прямо в Fastfile. В примере ниже используются только заполнители:

lane :testflight_upload do
  api_key = app_store_connect_api_key(
    key_id: ENV.fetch("ASC_KEY_ID"),
    issuer_id: ENV.fetch("ASC_ISSUER_ID"),
    key_filepath: ENV.fetch("ASC_KEY_PATH")
  )

  upload_to_testflight(
    api_key: api_key,
    skip_waiting_for_build_processing: true
  )
end

Действие app_store_connect_api_key поддерживает key_id, issuer_id и путь к .p8; передача ключа в Lane через объект API Key также описана в документации fastlane для app_store_connect_api_key.

Сначала отключите автоматическое представление версии на проверку. TestFlight нужен как промежуточная контрольная точка: вы проверяете, что файл загружен, обработан, связан с нужной версией и доступен тестировщикам. App Store Connect различает загрузку, обработку, доступность сборки и дальнейшее представление на проверку.

Если сборка создана, но App Store Connect её не принял

Разбирайте сбой по состоянию, а не по общей фразе «fastlane не работает»:

1. Команда завершилась до загрузки — проверьте API Key, путь к .p8, Issuer ID и роль.
2. Файл отправлен, но отклонён сразу — проверьте Bundle ID, версию, build number и экспортный метод.
3. Загрузка завершилась, но сборка не видна — дождитесь обработки и изучите статус доставки в App Store Connect.
4. Версия не связана с записью приложения — сравните Bundle ID и номер версии внутри .ipa.
5. Сбой повторяется после исправления — сохраните новый лог отдельно и не перезапускайте весь процесс вслепую.

Для проверки содержимого архива используйте:

unzip -l build/Example.ipa
codesign -dvvv --entitlements :- build/Payload/Example.app

Путь внутри .ipa может отличаться, поэтому сначала найдите имя приложения командой unzip -l. Если загрузка прервалась после передачи файла, не увеличивайте build number автоматически: сначала установите, был ли файл принят. Иначе вы создадите несколько версий и усложните сопоставление журналов.

Первая неделя: превращение Lane в постоянный сборочный процесс

После успешной ручной TestFlight-загрузки добавьте автоматизацию по одному элементу:

1. получить нужную ветку через Git;
2. проверить активный путь xcode-select;
3. установить Ruby-зависимости через bundle install;
4. восстановить секреты и хранилище подписи;
5. синхронизировать match в режиме readonly;
6. проверить свободное место и состояние Keychain;
7. увеличить build number по заранее выбранному правилу;
8. создать Archive;
9. загрузить .ipa;
10. сохранить лог, commit и итоговый статус.

Для проверки Xcode задайте явный путь:

xcode-select -p
xcodebuild -version

Если на машине установлены несколько Xcode, используйте DEVELOPER_DIR или действие xcodes, а не полагайтесь на случайно выбранную активную версию.

Разделяйте безопасные и потенциально повторяющие операции:

• Git pull, установка зависимостей и проверка диска обычно можно повторять;
• Archive можно повторить после очистки временных файлов;
• загрузку следует повторять только после проверки статуса доставки;
• увеличение build number нельзя запускать повторно без понимания, какая версия уже принята;
• отзыв сертификатов и создание новых профилей не должны выполняться в автоматической задаче.

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

Какой вариант подходит для постоянной работы

Внутри вашей команды отдельно зафиксируйте, кто может менять сертификаты, кто только запускает сборку и кто имеет доступ к API Key. Так вы не смешаете права публикации, права подписи и права управления пользователями.

Приёмка удалённого Mac перед регулярными релизами

Поскольку у разных проектов отличаются SDK, количество target и требования к подписи, оценивайте не обещанную конфигурацию, а фактический прогон на вашей ревизии кода. Перед долгосрочной эксплуатацией проверьте следующие пункты:

Если для работы нужен постоянно доступный узел, сравните требования проекта с вариантами аренды удалённого Mac в VPSMAC. Для разработчика из Европы и восточной части США также имеет смысл заранее проверить задержку SSH и графического доступа до выбранного узла Mac в Вирджинии, но саму пригодность машины подтверждайте только реальным Archive и загрузкой вашего приложения.

Когда переходить от ручного запуска к расписанию

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

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

Постоянно работающий удалённый Mac оправдан, если вам нужны:

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

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

Если сейчас вы используете Windows или Linux как единственное окружение, ручная передача проекта на чужую машину создаёт три постоянных недостатка: непредсказуемую версию Xcode, слабую наблюдаемость логов и зависимость от доступности другого человека. В такой ситуации аренда Mac в VPSMAC может быть более управляемым промежуточным решением, чем покупка отдельного Mac только ради редких релизов: вы сначала проходите настоящую приёмку по этой статье, а затем решаете, нужен ли вам недельный, месячный или более длительный доступ.

Начните не с автоматической кнопки «отправить на проверку», а с одной воспроизводимой Lane, которая после чистого запуска создаёт подписанный .ipa и делает его видимым в TestFlight. Когда этот маршрут подтверждён логами и повторным запуском, автоматическая отправка становится настройкой процесса, а не попыткой скрыть проблемы с окружением.