Xcode Product → Archive: полный разбор (и почему CI зависает на этом шаге)

1. Archive и Build: что меняется на самом деле

Многие команды сводят падения CI к формулировке «xcodebuild сломался». На практике Cmd+B Build и Product → Archive — это два разных пути:

Поэтому «3 минуты локально» и «20 минут в CI с падением» не противоречат друг другу: локально вы могли собирать Debug + симулятор, а в CI идёт Release + device-архитектура + полная цепочка подписи. Сначала выровняйте условия сравнения, потом оптимизируйте. Про разрыв по времени компиляции — в материале почему xcodebuild в CI в 2–3 раза медленнее локально.

2. От меню к CLI: эквивалент Product → Archive

Клик по Product → Archive в Xcode примерно соответствует:

1. Выбор Shared Scheme с конфигурацией Release;
2. Destination = Any iOS Device (не симулятор);
3. Запуск xcodebuild archive с записью в ARCHIVE_PATH;
4. (Опционально) Distribute App в Organizer → аналог xcodebuild -exportArchive.

Минимальная команда Archive для CI (пути подставьте под свой проект):

xcodebuild archive \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -archivePath "$RUNNER_TEMP/MyApp.xcarchive" \
  CODE_SIGN_STYLE=Manual \
  DEVELOPMENT_TEAM=XXXXXXXXXX \
  | tee archive.log

Три параметра, которые часто забывают:

• -destination 'generic/platform=iOS': без него xcodebuild может выбрать симулятор — Archive падает или ведёт себя непредсказуемо.
• -archivePath: путь должен быть доступен для записи; на hosted runner’ах проблемы с правами на temp дают «скомпилировалось, но архив не записался».
• Scheme должен быть Shared и закоммичен в Git: локальный unshared Scheme после checkout в CI не существует → scheme not found.

Официальные материалы: Apple — Building your app, Distributing your app.

3. Четыре этапа пайплайна

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ 1. Resolve   │ →  │ 2. Archive   │ →  │ 3. Sign      │ →  │ 4. Export    │
│ SPM/Pods     │    │ Release full │    │ Certs/profiles│    │ IPA / Upload │
│ DerivedData  │    │ → .xcarchive │    │ Keychain auth │    │ TestFlight   │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
     pod install          xcodebuild           codesign           exportArchive
     часто 5–15 мин       archive 8–25 мин     зона «тишины»      ошибки plist

Когда CI «зависает здесь», спросите себя: к какому этапу относится последняя строка лога? Остановка на CompileSwift — это компиляция; на CodeSign — подпись; на exportArchive — конфиг экспорта. Смешивание этапов приводит к бесконечной очистке кешей.

4. Этап 1: Resolve и Compile (почему CI медленнее)

Разрешение зависимостей и компиляция перед Archive локально обычно «прогреты», а в CI — «холодные»:

• CocoaPods / SPM: CI каждый job запускает pod install с нуля — в логах Installing …, и 10 минут уходит ещё до Archive. См. кеширование Pods и DerivedData во Flutter iOS CI.
• Холодный DerivedData: полная Release-сборка без кеша перекомпилирует каждый native-модуль Pod’ов. Фиксация DERIVED_DATA_PATH на SSD self-hosted runner’а часто сокращает второй Archive вдвое.
• Давление на память: Archive потребляет больше, чем Debug; Mac на 16 ГБ с параллельными job’ами уходит в swap — CPU низкий, а прогресса нет. См. управление памятью и swap на runner’е.

Быстрая проверка: если в логах много CompileC / SwiftCompile для сторонних pod’ов, которые вы не трогали, сначала чините кеш — не подпись.

5. Этап 2: Archive (создание .xcarchive)

После успешного xcodebuild archive по пути -archivePath должна появиться такая структура:

MyApp.xcarchive/
  Info.plist
  Products/Applications/MyApp.app
  dSYMs/...

Типичные сбои:

• В Archive action Scheme не отмечен target: локально собирается один Scheme, а CI-Scheme архивирует пустоту.
• Multi-target / extension: основное приложение проходит, Notification Service Extension падает на подписи — весь Archive считается failed.
• Конфликт build number / version: CI не инкрементирует CFBundleVersion; upload падает позже, а винят «медленный Archive».

Проверяйте сразу: ls -la "$ARCHIVE_PATH" и plutil -p "$ARCHIVE_PATH/Info.plist" — убедитесь, что есть ApplicationProperties. Не ждите падения export, чтобы обнаружить неполный архив.

6. Этап 3: Code Sign (главная ловушка CI)

Локально Archive может запросить доступ к keychain — вы жмёте «Always Allow», и пайплайн идёт дальше. Безконсольный CI такого шага не имеет, поэтому:

• errSecInternalComponent, User interaction is not allowed: приватный ключ в login keychain, CI-пользователь не может авторизовать через GUI.
• Просроченный profile / несовпадение Bundle ID: лог замирает на CodeSign с Provisioning profile … doesn't match.
• Случайное включение -allowProvisioningUpdates: требует интерактивный вход Apple ID; headless-среда ждёт бесконечно.
• Keychain не разблокирован: в job нет security unlock-keychain / set-key-partition-list в начале.

На облачном Mac / self-hosted runner’е рекомендуем: отдельный keychain-файл (не login keychain), импорт distribution-сертификата + приватного ключа, разблокировка и установка default в начале job. Полная цепочка — в статье iOS CI на облачном Mac: codesign и границы keychain.

# Начало job (пароль — через CI Secret)
KEYCHAIN=$RUNNER_TEMP/ci-signing.keychain-db
security create-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN"
security import dist.p12 -k "$KEYCHAIN" -P "$P12_PASSWORD" -T /usr/bin/codesign
security set-key-partition-list -S apple-tool:,apple: -s -k "$KEYCHAIN_PASSWORD" "$KEYCHAIN"
security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN"
security list-keychains -s "$KEYCHAIN" login.keychain-db

Если используете fastlane match или Xcode Cloud для credentials — принцип тот же: процесс CI должен получить доступ к приватному ключу без участия человека, а не просто «сертификат где-то лежит на машине». См. fastlane match.

7. Этап 4: Export IPA (exportArchive)

Archive создаёт только .xcarchive; для загрузки в TestFlight нужен ещё Export. Distribute App в меню соответствует:

xcodebuild -exportArchive \
  -archivePath "$RUNNER_TEMP/MyApp.xcarchive" \
  -exportPath "$RUNNER_TEMP/export" \
  -exportOptionsPlist ExportOptions.plist

Ключ method в ExportOptions.plist задаёт тип экспорта (app-store, ad-hoc, development и т.д.). Частые проблемы в CI:

• method не совпадает с типом profile: development profile + app-store method.
• Нет teamID / signingCertificate: ошибки Manual signing всплывают на export и маскируются под «медленный Archive».
• Upload в одном step с export: сетевая задержка altool / Transporter попадает в «таймаут Archive».

jobs:
  archive-ios:
    runs-on: [self-hosted, macOS, ios]  # или macos-14 hosted runner
    timeout-minutes: 60
    steps:
      - uses: actions/checkout@v4

      - name: Install pods
        run: pod install --deployment
        working-directory: ios

      - name: Archive
        run: |
          set -o pipefail
          xcodebuild archive \
            -workspace ios/MyApp.xcworkspace \
            -scheme MyApp \
            -configuration Release \
            -destination 'generic/platform=iOS' \
            -archivePath "$RUNNER_TEMP/MyApp.xcarchive" \
            | tee archive.log
        env:
          DEVELOPER_DIR: /Applications/Xcode_16.4.app/Contents/Developer

      - name: Export IPA
        run: |
          xcodebuild -exportArchive \
            -archivePath "$RUNNER_TEMP/MyApp.xcarchive" \
            -exportPath "$RUNNER_TEMP/export" \
            -exportOptionsPlist ios/ExportOptions.plist