Fastfile: 모바일 개발에서 자동화의 본질, 구조 및 설정

Fastfile이란 무엇이며 왜 필요한가

Fastfile은 Ruby로 작성되어 프로젝트 루트의 fastlane 디렉터리에 배치되는 Fastlane의 기본 구성 파일입니다. 애플리케이션 빌드, 테스트, 코드 서명 및 전송을 위한 모든 자동화 시나리오(lanes)를 정의합니다. Fastfile은 수십 개의 bash 스크립트, Makefile 및 수동 지침을 단일 선언적 CI/CD 파이프라인 설명으로 대체합니다.

Fastfile의 필요성은 프로젝트가 여러 개발자 머신과 CI/CD 서버에서 반복 가능한 빌드를 필요로 할 때 발생합니다. 각 개발자가 수동으로 환경을 설정하는 대신, Fastfile은 Git에서 버전 관리, 검토 및 프로젝트 간 재사용이 가능한 코드로 모든 단계를 캡처합니다. 단일 Fastfile은 개발자 머신의 빌드가 CI/CD 서버의 빌드와 동일함을 보장합니다.

Fastfile은 default_platform 지시문을 통해 플랫폼을 지원합니다. 하나의 Fastfile에서 iOS, Android 및 macOS에 대한 시나리오를 설명하고 platform :ios 및 platform :android 블록으로 그룹화할 수 있습니다. 이는 iOS와 Android 빌드가 공통 배포 로직을 공유하지만 다른 빌드 도구를 사용하는 크로스 플랫폼 프로젝트에 특히 유용합니다.

Fastfile 구조: lanes, actions 및 매개변수

Fastfile은 세 가지 주요 요소로 구성됩니다: 플랫폼 선언(default_platform), lanes 정의 및 도우미 함수 구성. 각 lane은 키워드 lane으로 시작하며, 시나리오 이름(Ruby 심볼), 작업 시퀀스가 있는 본문 및 오류 처리 블록(error, success 또는 ensure)이 이어집니다.

Fastfile의 Actions은 Hash 형태의 매개변수와 함께 내장 Fastlane 함수를 호출하는 것입니다. 예를 들어, gym(scheme: 'App', export_method: 'app-store')은 지정된 매개변수로 iOS 앱 빌드를 시작합니다. 각 action은 변수에 저장하고 후속 actions에서 사용할 수 있는 결과를 반환합니다. 이를 통해 lane 내에서 조건부 로직이 가능합니다.

Fastfile은 Ruby의 표준 ENV 메커니즘을 통해 환경 변수를 지원합니다. 민감한 데이터(비밀번호, 토큰, 키)는 Fastfile에 저장하면 안 됩니다. CI/CD 시스템 환경 변수 또는 .gitignore에 추가된 .env 파일을 사용하세요. Fastlane은 시작 시 fastlane 디렉터리에서 .env 파일을 자동으로 로드합니다.

Appfile 및 Matchfile

Fastfile과 함께 fastlane 디렉터리에는 추가 구성 파일이 있습니다. Appfile에는 애플리케이션 식별자(app_identifier), Apple ID 및 Team ID가 포함됩니다. 이 데이터는 자동으로 모든 actions에 대체되어 각 lane에서의 반복을 제거합니다. Matchfile은 match 설정을 저장합니다: Git 저장소 URL, 프로필 유형 및 암호화 키.

구성을 여러 파일로 분할하면 다른 환경을 가진 프로젝트의 유지 관리가 간소화됩니다. 예를 들어, 스테이징 및 프로덕션을 위해 Matchfile 저장소에서 별도의 브랜치를 만들거나 CI/CD 시스템의 환경 변수를 통해 매개변수를 재정의할 수 있습니다.

# 기본 Fastfile 구조
default_platform(:ios)

lane :build_and_test do
  cocoapods
  scan(scheme: 'App', devices: ['iPhone 15'])
  gym(scheme: 'App')
end

lane :deploy do
  match(type: 'appstore')
  build_and_test
  pilot(skip_waiting_for_build_processing: true)
end

Fastfile 구문: lanes 작성

Fastfile 구문은 자동화 시나리오의 가독성을 위해 특별히 설계된 Ruby DSL(도메인 특화 언어)을 기반으로 합니다. Lane은 lane :name do ... end 구문을 통해 선언되며, name은 터미널 또는 CI/CD 시스템에서 실행하기 위한 fastlane name 명령이 되는 Ruby 심볼입니다.

Lane 내에서는 로직 분기를 위해 Ruby 조건 연산자: if, unless, case를 사용할 수 있습니다. 값 배열을 처리하기 위한 루프 each 및 while도 사용할 수 있습니다. Fastlane은 lane 수명 주기 이벤트 처리를 위한 특별한 메서드 before_all, after_all 및 error 블록을 제공합니다.

Lane 매개변수는 options 해시를 통해 전달됩니다. fastlane build --option_name value를 실행하면 값이 lane 내의 options[:option_name]에 들어갑니다. optional: true 및 유형 검증을 통해 기본값을 설정하고 전달되는 매개변수의 유형을 제어할 수 있습니다.

# 매개변수 및 조건부 로직이 있는 Lane
lane :build do |options|
  scheme = options[:scheme] || 'App'
  export_method = options[:export_method] || 'development'

  match(type: export_method)

  if export_method == 'appstore'
    gym(scheme: scheme, export_method: 'app-store')
    pilot(skip_waiting_for_build_processing: true)
  else
    gym(scheme: scheme, export_method: export_method)
  end
end

iOS 전송을 위한 Fastfile 예제

iOS 프로젝트를 위한 완전한 Fastfile에는 종속성 설치, 테스트, 빌드 및 TestFlight와 App Store에 배포하기 위한 lanes가 포함됩니다. 커밋부터 내부 테스트를 위한 TestFlight 게시까지의 일반적인 CI/CD 프로세스를 다루는 예제를 살펴보겠습니다.

# iOS CI/CD 전송용 Fastfile
default_platform(:ios)

before_all do
  cocoapods(try_repo_update_on_error: true)
  setup_travis if ENV['TRAVIS']
end

lane :tests do
  scan(
    scheme: 'App',
    devices: ['iPhone 15', 'iPad Pro 12.9'],
    output_directory: './test_reports'
  )
end

lane :build_appstore do
  match(type: 'appstore', readonly: true)
  gym(
    scheme: 'App',
    export_method: 'app-store',
    include_bitcode: true
  )
end

lane :deploy_testflight do
  build_appstore
  pilot(
    skip_waiting_for_build_processing: true,
    distribute_external: false
  )
  slack(
    message: '내부 테스트를 위해 TestFlight에 빌드 업로드됨'
  )
end

이 예제에서 before_all 블록은 각 lane 전에 실행되며 종속성을 설치합니다. tests lane은 두 장치에서 UI 및 단위 테스트를 실행합니다. build_appstore lane은 match를 통해 코드에 서명하고 bitcode로 IPA를 빌드합니다. deploy_testflight lane은 완전한 전송을 위해 모든 단계를 결합합니다.

여러 대상으로 배포

여러 대상(기본 앱, watchOS, widget, Notification Service Extension)이 있는 프로젝트는 각 대상에 대해 별도의 lanes가 필요합니다. Fastfile에서는 스키마 이름과 빌드 경로를 매개변수로 받는 범용 lane :deploy_target을 만들 수 있습니다. 이를 통해 fastlane deploy_target scheme:Widget로 모든 확장 기능에 대한 배포를 실행할 수 있습니다.

여러 대상을 구성하려면 스키마 배열과 lane 내의 each 루프를 사용하세요. Fastlane은 parallel: true 플래그를 통해 여러 스키마의 병렬 빌드를 지원하여 확장 기능이 있는 앱의 전체 CI/CD 파이프라인 시간을 줄입니다.

Android 빌드를 위한 Fastfile 예제

Android 프로젝트용 Fastfile은 Gradle 작업을 실행하기 위한 gradle action과 Google Play에 게시하기 위한 supply action을 사용합니다. iOS와 달리 Android는 match가 필요하지 않지만 서명을 위해 Keystore를 사용하며, 이는 저장소 외부에 저장되고 환경 변수를 통해 전달됩니다.

# Android CI/CD 빌드용 Fastfile
default_platform(:android)

lane :build_release do
  gradle(task: 'clean')
  gradle(task: 'bundleRelease')
  gradle(task: 'assembleRelease')
end

lane :deploy_internal do
  build_release
  supply(
    track: 'internal',
    aab: 'app/build/outputs/bundle/release/app-release.aab',
    release_status: 'completed'
  )
end

Android 앱 서명의 경우 build.gradle에서 signingConfigs를 구성하고 환경 변수를 통해 Keystore 매개변수를 전달합니다: ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS 및 ANDROID_KEY_PASSWORD. Fastlane은 자동으로 시스템 apksigner를 사용하여 빌드된 AAB 또는 APK에 서명합니다.

Fastfile에서 Android 서명

Fastfile에서 Android 서명을 구성하려면 sign_android action을 사용하거나 build.gradle의 signingConfigs에 의존하세요. Fastlane은 Gradle을 통해 apksigner와 통합됩니다. gradle 작업에 SIGNING_CONFIG 플래그를 전달하면 환경 변수의 매개변수로 서명이 활성화됩니다. 이를 통해 Google Play Console에 업로드하기 전에 AAB 파일에 서명할 수 있습니다.

CI/CD에서 Keystore의 안전한 저장을 위해 Base64 인코딩과 환경 변수를 사용하세요. Fastlane은 setup_keystore action을 지원하며, 변수에서 Keystore를 디코딩하여 before_all 단계 동안 임시 파일에 저장합니다. Lane이 완료되면 인증서 유출을 방지하기 위해 임시 파일이 자동으로 삭제됩니다.

Private lanes 및 그룹 사용

Private lanes(비공개 시나리오)는 명령줄에서 직접 호출할 수 없지만 Fastfile 내의 다른 lanes에서 호출할 수 있는 lanes입니다. Private lane은 private_lane :name do ... end 구문을 통해 선언되며 독립 시나리오로 의미가 없는 반복 단계를 캡슐화하는 데 사용됩니다.

Private lanes은 반복 로직 그룹화에 이상적입니다: 종속성 설치, 환경 설정, 알림 보내기. 예를 들어, 여러 배포 lanes에서 호출되는 private lane :setup_signing을 만들 수 있지만, 오류를 방지하기 위해 개발자가 직접 실행할 수 없어야 합니다.

# Private lane 및 그룹화
default_platform(:ios)

private_lane :setup_signing do |options|
  match(
    type: options[:type],
    readonly: true,
    verbose: false
  )
end

lane :beta do
  setup_signing(type: 'adhoc')
  gym(export_method: 'ad-hoc')
  pilot(distribute_external: true)
end

lane :release do
  setup_signing(type: 'appstore')
  gym(export_method: 'app-store')
  deliver(
    force: true,
    submit_for_review: true
  )
end

platform 블록을 통한 lanes 그룹화는 하나의 Fastfile에서 iOS와 Android 시나리오를 분리할 수 있습니다. platform :ios do ... end 및 platform :android do ... end 구문은 해당 플랫폼의 lanes를 분리하며, 공통 private lanes은 재사용을 위해 플랫폼 블록 외부에 배치할 수 있습니다.

Lanes에 매개변수 전달

Fastfile의 매개변수 메커니즘은 lanes를 유연하고 재사용 가능하게 만듭니다. 매개변수는 런타임에 명령줄을 통해 전달됩니다: fastlane build scheme:App export_method:appstore. Lane 내에서 값은 lane 블록에 인수로 전달되는 options 해시를 통해 액세스할 수 있습니다.

Fastlane은 OptionalHash를 통한 검증이 있는 유형화된 매개변수를 지원합니다. 값 유형(String, Boolean, Integer), 기본값 및 문서 자동 생성을 위한 설명을 지정할 수 있습니다. 환경 변수도 매개변수를 전달하는 대체 방법으로 사용할 수 있으며, 이는 CI/CD 시스템에 편리합니다.

# 유형 검증이 있는 매개변수
lane :build do |options|
  gym(
    scheme: options[:scheme],
    export_method: options[:export_method] || 'development',
    include_bitcode: options[:include_bitcode] || false,
    output_name: options[:output_name]
  )
  slack(message: "빌드: #{options[:scheme]} 완료")
end

# 실행: fastlane build scheme:MyApp export_method:appstore

모든 선택적 매개변수에 대해 기본값을 사용하는 것이 좋습니다. 그러면 각 인수를 명시적으로 지정하지 않고 lane을 실행할 수 있습니다. 필수 매개변수의 경우 lane 시작 부분에서 해당 존재를 확인하고 UI.user_error!를 통해 명확한 오류 메시지와 함께 실행을 중단합니다.