Ошибка Two-factor authentication required при запуске fastlane почти всегда означает, что утилита не может подтвердить сессию Apple ID, и именно в этот момент разработчику требуется код восстановления или одноразовый код подтверждения. Без него загрузка сборки через fastlane deliver или fastlane pilot останавливается на этапе авторизации в App Store Connect.
Термин «код восстановления» в контексте fastlane используется в двух смыслах: это и одноразовый код двухфакторной аутентификации (2FA), который Apple присылает на доверенное устройство, и резервные коды восстановления аккаунта Apple ID, если доступ к доверенным устройствам утерян. Разберём оба сценария и способы обойти ручной ввод кодов в CI/CD.
Зачем Fastlane запрашивает код подтверждения
Apple требует двухфакторную аутентификацию для учётных записей разработчиков. Когда fastlane обращается к App Store Connect от имени вашего Apple ID, сервер может потребовать подтверждение личности — особенно при входе с нового IP-адреса или после истечения сессии.
При интерактивном запуске утилита выводит запрос в терминал и ждёт ввода шестизначного кода. На CI-сервере интерактивный ввод невозможен, поэтому сборка падает с ошибкой тайм-аута или отказа в доступе.
- 🔑 Одноразовый 2FA-код — приходит на доверенное устройство Apple или по SMS, действует ограниченное время.
- 🛟 Резервные коды восстановления — генерируются в настройках Apple ID и используются при потере доступа к доверенным устройствам.
- 🤖 Пароль приложения или API-ключ — заменяет интерактивный ввод кода для автоматизированных сценариев.
Как ввести код при интерактивном запуске
Запустите нужную команду, например fastlane beta или fastlane deliver. Когда Apple запросит подтверждение, в терминале появится приглашение вида Please enter the 6 digit code:. Одновременно на доверенном iPhone, iPad или Mac появится push-уведомление с кодом.
Введите шесть цифр и нажмите Enter. Если код не пришёл, проверьте, что доверенное устройство подключено к интернету, или запросите отправку по SMS на доверенный номер телефона через интерфейс Apple ID.
После успешного ввода fastlane сохраняет сессию в локальном кеше, и некоторое время повторный ввод кода не требуется. Срок жизни сессии определяется сервером Apple и заранее не гарантируется.
Коды восстановления Apple ID: где взять и как хранить
Если доступ к доверенным устройствам утерян — например, телефон сломан или продан без сброса — вход в аккаунт выполняется через процедуру восстановления Apple ID. В зависимости от настроек безопасности могут использоваться резервные коды, которые генерируются в разделе безопасности учётной записи.
Точный путь в меню зависит от версии iOS и macOS, поэтому сверяйтесь с актуальной документацией Apple. Общий принцип: откройте настройки Apple ID, перейдите в раздел «Вход и безопасность» (или аналогичный) и найдите опцию резервных кодов, если она предусмотрена для вашего типа аккаунта.
⚠️ Внимание: резервные коды показываются один раз при генерации. Сохраните их в менеджере паролей или распечатайте и храните офлайн. Повторно просмотреть их нельзя — можно только сгенерировать новый набор, после чего старые коды перестанут действовать.
Что делать, если все коды потеряны и устройств нет
Запустите процедуру восстановления доступа на сайте Apple ID. Apple может запросить подтверждение личности и применить период ожидания — это нормальная часть защиты аккаунта. Для корпоративных учётных записей разработчика обратитесь к владельцу команды (Account Holder) или в поддержку Apple Developer.
Автоматизация: как избежать ручного ввода кодов
Для CI/CD ввод 2FA-кода вручную неприемлем. Apple и fastlane предлагают несколько официальных способов обойти интерактивную аутентификацию.
Рекомендуемый вариант — ключ API App Store Connect. Он создаётся в разделе «Users and Access → Keys» веб-интерфейса App Store Connect и не требует двухфакторного подтверждения при каждом запросе. Fastlane поддерживает его нативно через app_store_connect_api_key.
lane :release do
api_key = app_store_connect_api_key(
key_id: "YOUR_KEY_ID",
issuer_id: "YOUR_ISSUER_ID",
key_filepath: "./AuthKey.p8"
)
upload_to_testflight(api_key: api_key)
end
☑️ Настройка API-ключа для fastlane
Альтернатива — переменная окружения FASTLANE_SESSION, содержащая сериализованную сессию, полученную командой fastlane spaceauth. Сессия периодически истекает, поэтому этот метод требует регулярного обновления и считается менее надёжным, чем API-ключ.
Сравнение способов аутентификации в Fastlane
| Способ | Интерактивный ввод | Подходит для CI | Ограничения |
|---|---|---|---|
| Ручной ввод 2FA-кода | Да | Нет | Код действует ограниченное время |
| App Store Connect API Key | Нет | Да | Не покрывает все операции с аккаунтом |
| FASTLANE_SESSION (spaceauth) | Один раз при создании | Да | Сессия истекает, требует обновления |
| Application-specific password | Нет | Частично | Работает не со всеми сервисами Apple |
Выбор зависит от задачи: для загрузки сборок и скриншотов оптимален API-ключ, а для операций, которые API-ключ не поддерживает, придётся комбинировать его с сессией spaceauth.
Типичные ошибки и их решение
Ошибка Invalid session или повторный запрос кода сразу после ввода обычно означает, что сессия не сохранилась. Проверьте, что у пользователя, от имени которого запускается fastlane, есть права на запись в домашнюю директорию — именно там кешируются данные сессии.
Если код приходит, но система отклоняет его, убедитесь, что время на машине синхронизировано. Рассинхронизация часов — возможная причина отказа сервера принимать одноразовые коды. Также проверьте, что вы вводите код именно для того Apple ID, который указан в Fastfile или переменных окружения.
⚠️ Внимание: несколько подряд неудачных попыток ввода кода могут привести к временной блокировке Apple ID. Если код отклонён дважды, остановитесь, проверьте правильность учётной записи и дождитесь нового кода вместо перебора старых.
- 🕐 Проверьте синхронизацию времени на машине сборки.
- 👤 Убедитесь, что используется правильный Apple ID из Fastfile.
- 🔄 Запросите свежий код — старые коды недействительны после отправки нового.
- 🔐 При частых сбоях переходите на API-ключ вместо сессионной аутентификации.
FAQ: частые вопросы о кодах восстановления в Fastlane
Fastlane сам генерирует код восстановления?
Нет. Fastlane — клиентский инструмент: все коды выдаёт Apple. Утилита только запрашивает код у пользователя и передаёт его серверу для подтверждения входа.
Можно ли отключить двухфакторную аутентификацию для аккаунта разработчика?
Для учётных записей Apple Developer двухфакторная аутентификация является обязательным требованием Apple. Обходить её нельзя — вместо этого используйте API-ключи для автоматизации.
Что делать, если на CI постоянно истекает FASTLANE_SESSION?
Это ожидаемое поведение: сессии Apple имеют ограниченный срок действия. Либо периодически обновляйте сессию через fastlane spaceauth на доверенной машине, либо мигрируйте на App Store Connect API Key, который не истекает по таймеру.
Подходит ли application-specific password для всех команд fastlane?
Нет. Пароль приложения работает с частью сервисов Apple, но не заменяет полноценную сессию или API-ключ. Для загрузки сборок надёжнее использовать API-ключ App Store Connect.
Где безопасно хранить резервные коды Apple ID команды разработчиков?
В корпоративном менеджере секретов с разграничением доступа. Не храните коды в репозитории, общих документах или мессенджерах — это равнозначно передаче ключа от аккаунта.