Gym (Fastlane): 개념, IPA 빌드 및 앱 개발 자동화

Gym(Fastlane)이란?

Gym(Fastlane)은 Fastlane 생태계의 구성 요소로, 단일 터미널 명령으로 iOS 애플리케이션을 IPA 형식으로 빌드합니다. 수십 개의 플래그로 xcodebuild를 호출하는 복잡한 프로세스를 추상화하고 개발자에게 합리적인 기본값과 함께 간단한 인터페이스를 제공합니다.

Xcode에서 IPA를 빌드하려면 프로젝트를 열고, 스키마를 선택하고, Archive와 Export를 설정하고, 배포 방법을 지정하고, 완료를 기다려야 합니다. Gym을 통한 빌드 자동화는 수동 단계를 제거하고 모든 빌드가 동일한 매개변수로 실행되도록 보장합니다 — 이는 예측 가능한 CI/CD 파이프라인에 매우 중요합니다.

SwiftLee(2024)에 따르면, Gym을 사용하여 빌드하는 팀은 Xcode Organizer를 통한 수동 내보내기와 비교하여 릴리스 프로세스 설정에 40% 적은 시간을 소비합니다. Gym은 또한 각 xcodebuild 단계에 대한 자세한 빌드 로그를 생성하여 실패한 빌드의 디버깅과 컴파일 오류 분석을 간소화합니다.

테스트 또는 게시를 위해 정기적인 IPA 빌드가 필요한 모든 iOS 프로젝트에서 Gym을 사용하세요 — 팀의 모든 머신에서 동일한 빌드 구성을 보장하는 유일한 방법입니다.

Gym이 IPA를 빌드하는 방법: 프로세스 및 매개변수

Gym을 통한 IPA 빌드 프로세스

Gym을 통한 IPA 빌드는 세 가지 순차적 단계로 구성됩니다: xcodebuild를 통한 프로젝트 아카이빙, 아카이브의 바이너리 패키지로 내보내기, 서명과 함께 IPA 형식으로 패키징. Gym은 프로젝트 유형(단일 target 또는 workspace)을 자동으로 감지하고 올바른 빌드 방법을 선택합니다.

아카이빙 단계에서 Gym은 프로젝트에 지정된 스키마 및 설정 매개변수로 xcodebuild archive를 실행합니다. 아카이브(.xcarchive) 생성에 성공하면 Gym은 선택한 내보내기 방법으로 xcodebuild -exportArchive를 실행합니다. IPA 내보내기는 .xcarchive를 필요한 모든 리소스와 서명을 포함하는 설치 가능한 .ipa 파일로 변환하는 프로세스입니다.

빌드 내보내기 매개변수

내보내기 방법은 IPA 서명에 사용되는 Provisioning Profile의 유형을 결정합니다. Gym은 네 가지 방법을 지원합니다: development(개발자 기기에서 디버깅용), app-store(App Store 게시용), ad-hoc(제한된 기기에서 베타 테스트용), enterprise(기업 배포용).

추가 매개변수에는 세밀한 내보내기 구성을 위한 export_options_plist 지정, IPA 크기 축소를 위한 Swift overlay 억제, 비트코드 관리가 포함됩니다. Gym은 또한 --skip_package_ipa 플래그를 통한 시뮬레이터 빌드를 지원하며, 전체 내보내기 없이 빠른 코드 확인에 유용합니다.

# Gym을 통한 기본 IPA 빌드
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# 내보내기 방법을 지정한 빌드
fastlane gym --export_method app-store

# IPA 내보내기 없는 아카이브만 빌드
fastlane gym --skip_package_ipa

Gymfile을 통한 Gym 설정

Gymfile은 모든 빌드 매개변수를 구조화된 Ruby 형식으로 저장하는 Fastlane 설정 파일입니다. 명령줄을 통해 플래그를 전달하는 것과 달리, Gymfile을 사용하면 설정을 저장소에 커밋하고 모든 개발자와 CI가 동일한 빌드 설정을 사용하도록 보장할 수 있습니다.

# Gymfile — 빌드 구성
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

Gymfile의 export_method 매개변수는 Apple Developer Portal의 프로필 유형에 해당합니다. App Store 릴리스에는 :app-store를, 테스트에는 :development 또는 :ad-hoc을 사용합니다. configuration 매개변수는 빌드 설정을 정의합니다: 릴리스용 Release 또는 디버그 빌드용 Debug.

include_bitcode 매개변수는 IPA에 비트코드 포함을 제어합니다. Apple은 watchOS 및 tvOS 애플리케이션에 비트코드를 요구했지만, iOS에서는 바이너리 크기를 줄이기 위해 이 매개변수를 비활성화할 수 있습니다. include_symbols는 .dSYM 심볼 디버그 파일을 포함하며, App Store Connect 또는 타사 모니터링 서비스의 크래시 로그 심볼화에 필요합니다.

추가 Gymfile 매개변수에는 사용자 지정 plist 내보내기 파일을 위한 export_options_plist, 과도한 로그 출력을 억제하는 silent, 임시 빌드 디렉터리를 지정하는 build_path가 포함됩니다. 이러한 매개변수는 특정 아티팩트 요구 사항이 있는 복잡한 CI/CD 파이프라인에 Gym을 통합할 때 유용합니다.

애플리케이션 빌드를 위한 Gym 명령어

명령어 인터페이스 Gym에는 일반적인 빌드 시나리오를 위한 기본 매개변수와 정밀한 동작 조정을 위한 확장 플래그가 포함되어 있습니다. 대부분의 매개변수는 명령줄과 Gymfile을 통해 모두 전달할 수 있으며, 명령줄 인수가 설정 파일보다 우선합니다.

매개변수 없이 fastlane gym 명령어를 실행하면 Gymfile의 설정을 사용하거나 현재 디렉터리에서 프로젝트를 자동으로 감지합니다. 여러 target이 있는 프로젝트의 경우 올바른 target 빌드 구성을 선택하려면 --scheme과 --workspace를 지정해야 합니다.

일반적인 빌드 명령어

빠른 디버그 빌드를 위해 fastlane gym --export_method development를 사용합니다 — Development 프로필로 IPA를 빌드하여 개발자 기기에 설치합니다. App Store용 IPA 빌드에는 --export_method app-store 플래그와 Distribution 인증서가 필요하며, 이는 Match 또는 Keychain에 미리 구성되어 있어야 합니다.

# 커스텀 이름으로 App Store 빌드
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# 아카이브 전 정리(clean) 빌드
fastlane gym --clean --configuration Debug

# IPA 없는 시뮬레이터용 빌드
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

--clean 플래그는 시작 전에 이전 빌드의 임시 파일을 제거하여 오래된 캐시 사용을 방지하고 깨끗한 빌드를 보장합니다. --destination 플래그는 대상 플랫폼(iOS Simulator, iOS Device, macOS Catalyst)을 지정할 수 있습니다.

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

Gym CI/CD 통합은 지속적인 제공을 추구하는 iOS 개발 팀의 표준 관행입니다. Gym은 테스트 단계 이후, TestFlight 또는 App Store에 제출하기 전에 GitHub Actions, GitLab CI, Bitrise 또는 Jenkins 파이프라인에서 실행됩니다.

일반적인 iOS CI/CD 파이프라인에는 다음이 포함됩니다: 저장소 복제, CocoaPods 또는 SPM을 통한 종속성 설치, Match를 통한 인증서 설정, Gym을 통한 IPA 빌드, Pilot 또는 Deliver를 통한 업로드. GitLab CI는 GitLab의 지속적 통합 시스템으로, 저장소에 푸시할 때마다 빌드를 실행합니다.

# GitLab CI 빌드 단계 예시
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# IPA를 빌드 아티팩트로 저장
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

CI에서 Gym이 올바르게 작동하려면 xcodebuild가 인증서가 있는 Keychain에 액세스할 수 있어야 합니다. 이는 Gym을 실행하기 전에 security unlock-keychain 명령을 통해 수행됩니다. Match를 사용하는 경우 인증서가 자동으로 설치되며 별도의 Keychain 설정이 필요하지 않습니다 — Match가 빌드를 위한 임시 키체인을 생성합니다.

IPA 빌드가 성공한 후 후속 파이프라인 단계로 전달할 수 있습니다: Pilot을 통한 TestFlight 업로드 또는 Deliver를 통한 App Store Connect 전송. FASTLANE_APPLE_API_KEY 및 MATCH_PASSWORD를 포함한 Apple Developer 자격 증명을 저장하도록 CI 시스템 환경 변수를 구성하여 모든 파이프라인 단계가 대화형 입력 없이 작동하도록 합니다.

일반적인 Gym 빌드 오류

Gym을 사용할 때 개발자는 잘못된 xcodebuild 구성, 인증서 누락 또는 Xcode 버전 비호환성과 관련된 오류를 자주 접합니다. 오류 진단은 각 명령 완료 후 콘솔에 출력되는 전체 빌드 로그 분석부터 시작됩니다.

오류 “error: No matching provisioning profiles found”는 선택한 내보내기 방법에 적합한 Provisioning Profile이 없음을 나타냅니다. 해결 방법: Match 또는 Keychain에 지정된 export_method에 대한 유효한 프로필이 포함되어 있는지 확인하세요. Provisioning Profile은 성공적인 IPA 서명을 위해 애플리케이션 식별자 및 인증서 유형(Development 또는 Distribution)과 일치해야 합니다.

오류 “error: Signing for requires a development team”는 프로젝트에 개발 팀이 지정되지 않은 경우 발생합니다. 해결 방법: 프로젝트 빌드 설정에 DEVELOPMENT_TEAM을 추가하거나 export_team_id 매개변수를 통해 Gymfile에서 team_id를 지정합니다. 이는 여러 Apple Developer 계정으로 작업하는 프로젝트에 특히 중요합니다.

오류 “error: Multiple commands produce...”의 경우 workspace에서 서로 다른 target 간에 출력 파일 충돌이 발생합니다. 해결 방법: Xcode 프로젝트 Build Settings에서 각 target에 고유한 출력 경로를 설정하거나 Xcode 14 이상에서 기본적으로 활성화된 새 빌드 시스템을 사용합니다. Gym은 --use_legacy_build_system 플래그를 통해 두 옵션을 모두 지원합니다.