Pilot (Fastlane): 주요 개념, TestFlight 및 모바일 프로젝트를 위한 빌드 관리

Pilot(Fastlane)이란?

Pilot(Fastlane)은 모바일 애플리케이션의 베타 테스트를 위한 Apple 플랫폼인 TestFlight와의 작업을 자동화하는 Fastlane 에코시스템의 구성 요소입니다. Pilot은 빌드 업로드, 테스터 추가, 그룹 관리, 빌드 상태 추적 등 모든 일상적인 작업을 처리합니다.

Pilot이 없으면 베타 배포 프로세스는 다음과 같습니다. 개발자가 수동으로 App Store Connect를 열고, 앱을 선택하고, Xcode Organizer를 통해 IPA를 업로드하고, 테스터 그룹을 구성하고, 초대장을 보냅니다. TestFlight는 App Store에서 공식 출시 전에 테스터에게 앱의 베타 버전을 배포하는 Apple의 서비스입니다.

App Store Connect Help(2025)에 따르면 외부 테스터는 첫 번째 빌드 설치 전에 Beta App Review 프로세스를 거쳐야 하며, 이는 1~48시간이 소요됩니다. Pilot은 검토 상태를 자동으로 추적하고 빌드가 외부 테스터 그룹에 배포 준비가 되면 팀에 알립니다.

테스터에게 정기적으로 베타 빌드를 제공해야 하는 모든 프로젝트에서 Pilot을 사용하세요. iOS CI/CD 파이프라인의 표준 도구로, 예측 가능한 제공 프로세스를 보장합니다.

TestFlight를 위한 Pilot의 주요 기능

Pilot의 기능은 베타 빌드 관리의 전체 수명 주기를 다룹니다. 바이너리 파일 업로드부터 새 버전에 대한 테스터 알림까지, 각 기능은 예측 가능한 동작과 각 단계의 상세 로깅을 갖춘 별도의 명령어로 구현됩니다.

TestFlight에 빌드 업로드

fastlane pilot upload 명령어는 IPA 파일을 App Store Connect에 업로드하고 TestFlight에 새 빌드를 생성합니다. Pilot은 바이너리 파일의 유효성, 버전 호환성 및 앱 식별자를 자동으로 확인합니다. App Store Connect는 빌드 업로드, 메타데이터, 분석 및 판매 보고서를 포함한 애플리케이션 관리를 위한 Apple의 플랫폼입니다.

업로드 후 Pilot은 Apple이 바이너리 파일을 처리할 때까지 기다립니다. 프로세스는 빌드 크기에 따라 5~30분이 소요됩니다. 대기 중에 Pilot은 현재 처리 상태(Processing, Validating 또는 Ready)에 대한 정보와 함께 진행 표시줄을 표시합니다. 처리가 성공하면 빌드를 테스터 그룹에 할당할 수 있습니다.

테스터 그룹 관리

Pilot은 내부 및 외부 테스터 그룹 관리를 모두 지원합니다. 내부 테스터는 Apple Developer 팀의 구성원으로 Beta App Review를 거치지 않고 즉시 빌드에 액세스할 수 있습니다. 외부 테스터는 이메일로 초대된 사용자로, 첫 번째 설치 전에 검토 승인이 필요합니다.

fastlane pilot add 명령어는 이메일 또는 Apple ID로 그룹에 새 테스터를 추가합니다. Pilot은 자동으로 초대장을 보내고 테스터가 초대를 수락했는지 확인합니다. 대량 추가의 경우 --testers_file_path 매개변수를 사용하여 파일에서 이메일 목록을 전달할 수 있으며, 수백 명의 참가자로 구성된 테스터 그룹을 초기에 구성할 때 편리합니다.

# TestFlight에 새 빌드 업로드
fastlane pilot upload --ipa "build/MyApp.ipa"

# 그룹에 테스터 추가
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

Pilot 설정 및 구성

Pilot 구성은 별도의 구성 파일이 필요하지 않으며 Appfile(공통 Fastlane 파일) 또는 명령줄 인수를 통해 설정을 전달합니다. 주요 매개변수에는 앱의 apple_id, app_identifier, team_id 및 App Store Connect API에 액세스하기 위한 자격 증명이 포함됩니다.

인증을 위해 Pilot은 App Store Connect API Key(권장 방법) 또는 Apple ID 2단계 인증을 사용합니다. App Store Connect API Key는 App Store Connect에서 생성되는 액세스 키로, 비밀번호와 확인 코드를 대화식으로 입력하지 않고 API와 상호 작용할 수 있습니다.

# Appfile — Fastlane 공통 구성
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# Pilot 환경 변수
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

app_identifier 매개변수는 앱의 Bundle Identifier를 정의하며, Xcode 프로젝트 및 App Store Connect에 지정된 식별자와 일치해야 합니다. apple_id 매개변수는 2단계 인증 체계에서 인증에 사용되며, team_id는 계정이 여러 Apple Developer 팀에 연결된 경우 개발 팀을 선택하는 데 사용됩니다.

Pilot이 작동하려면 CI/CD 환경에서 App Store Connect API Key를 구성해야 합니다. 키는 App Store Connect → Users and Access → Keys → Generate API Key에서 생성됩니다. .p8 파일을 CI 시스템 시크릿에 저장하고 APP_STORE_CONNECT_API_KEY_PATH 환경 변수 또는 Pilot 명령어의 --api_key_path 매개변수를 통해 경로를 지정합니다.

빌드 관리를 위한 Pilot 명령어

Pilot 명령어 세트는 빌드 업로드, 테스터 관리, 상태 보기, 메타데이터 추적 등 모든 TestFlight 시나리오를 다룹니다. 각 명령어는 CI/CD 스크립트에서 추가 처리를 위해 구조화된 JSON 출력을 반환합니다.

빌드 상태 보기

fastlane pilot builds 명령어는 버전, 처리 상태 및 업로드 날짜와 함께 모든 앱 빌드 목록을 표시합니다. 빌드 상태는 다음 중 하나일 수 있습니다. Processing(Apple이 바이너리 파일을 처리 중), Ready(빌드를 배포할 수 있음), Rejected(유효성 검사 오류로 인해 빌드가 거부됨).

# TestFlight의 모든 빌드 목록 보기
fastlane pilot builds

# 테스터 그룹에 빌드 할당
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# 특정 빌드에 대한 정보 보기
fastlane pilot build_info --build_number 42

fastlane pilot distribute 명령어는 지정된 테스터 그룹에 빌드를 할당하고 알림을 보냅니다. --notify 매개변수는 새 빌드가 있음을 테스터에게 이메일 알림을 보내도록 활성화합니다. 이는 베타 테스터를 테스트 프로세스에 참여시키고 피드백을 가속화하는 데 중요합니다.

빌드 메타데이터를 관리하려면 --changelog 매개변수를 사용하여 새 버전의 변경 사항 설명 텍스트를 설정합니다. 이 텍스트는 TestFlight 앱의 테스트 초대장에서 테스터에게 표시됩니다. 각 빌드에서 주요 변경 사항, 수정된 버그 및 새로운 기능을 지정하는 것이 좋습니다.

CI/CD 파이프라인에 Pilot 통합

CI/CD에서의 Pilot은 iOS 앱 제공 파이프라인의 최종 단계입니다. Gym이 IPA를 빌드하고 테스트를 통과한 후 Pilot은 빌드를 TestFlight에 업로드하고 테스터 그룹에 배포합니다. 이를 통해 QA 팀은 리포지토리에 커밋한 후 몇 분 내에 새 앱 버전을 얻을 수 있습니다.

일반적인 iOS CI/CD 파이프라인에는 다음 순서가 포함됩니다. Match(인증서), Gym(IPA 빌드), Pilot(TestFlight에 업로드 및 배포). 각 단계는 이전 단계에 의존하여 유효하고 서명된 빌드만 테스터에게 제공되도록 보장합니다.

# Fastfile의 전체 파이프라인
lane :beta do
    match(type: :appstore)
    gym(scheme: "MyApp", export_method: "app-store")
    pilot("build/MyApp.ipa", groups: ["QA", "PM"])
end

업로드 명령어의 skip_waiting 매개변수를 사용하면 CI 작업 내에서 Apple의 바이너리 파일 처리 완료를 기다리지 않고 Pilot이 업로드 요청을 보내고 빌드 식별자를 받은 후 종료할 수 있습니다. 처리는 최대 30분까지 소요될 수 있으므로 CI 러너에서 대기 시간을 소비하지 않아 파이프라인이 빨라집니다.

CI에서 Pilot이 올바르게 작동하려면 App Store Connect API 키를 구성해야 합니다. .p8 키 파일을 CI 시스템의 보안 저장소에 저장하고 APP_STORE_CONNECT_API_KEY_PATH 환경 변수를 통해 경로를 전달합니다. Pilot은 이 키를 사용하여 2단계 인증 없이 API에 인증하며, 이는 자동화된 시나리오에 중요합니다.

Pilot 사용 시 일반적인 문제

Pilot을 사용할 때 개발자는 인증 오류, 잘못된 앱 구성 및 Apple 측의 바이너리 파일 처리 문제를 가장 자주 경험합니다. Pilot 문제 진단은 pilot builds 명령어를 통해 App Store Connect에서 빌드 상태를 확인하는 것으로 시작됩니다.

“Your app is not available for testing in TestFlight” 오류는 앱이 App Store Connect에서 테스트용으로 구성되지 않은 경우 발생합니다. 해결 방법: App Store Connect에서 TestFlight 섹션을 열고 앱에 대한 테스트를 활성화한 다음 Export Compliance가 암호화 유형에 맞게 올바르게 입력되었는지 확인합니다.

“Missing iOS Distribution signing identity” 오류는 키체인에 Distribution 인증서가 없음을 나타냅니다. 해결 방법: Pilot을 호출하기 전에 Match를 실행하여 올바른 인증서를 다운로드합니다. Distribution 인증서는 Development와 다르며 TestFlight 또는 App Store를 통해 배포하기 위한 빌드에 서명하는 데 사용됩니다.

“Invalid Provisioning Profile” 오류의 경우 빌드에 선택한 내보내기 방법에 잘못된 프로필이 포함되어 있습니다. 해결 방법: Gym이 Match의 프로필 유형과 일치하는 올바른 export_method를 사용하는지 확인합니다. 빌드가 development 프로필로 빌드된 경우 Pilot은 TestFlight에 업로드할 수 없습니다. app-store 또는 ad-hoc 프로필이 필요합니다.