더 이상 수동 배포는 그만! iOS 배포 자동화 구축기

들어가며

안녕하세요. 프롬 iOS 개발자 이도연입니다.

프롬 iOS 앱을 개발하면서 가장 번거로웠던 작업 중 하나가 바로 배포였습니다. 매번 배포할 때마다 적절한 브랜치로 체크아웃하고, Xcode를 켜서 xcconfig에서 버전을 변경하고, 아카이브를 기다리고, ipa 파일을 추출해서 Firebase Distribution에 업로드하고, TestFlight까지 다시 한번 업로드하는 과정을 반복해야 했죠.

각 단계마다 일일이 대기한 뒤 다음 작업을 이어가야 하는 번거로움은 물론, 브랜치 체크아웃이나 버전 관리에서 실수가 발생하기도 했습니다.

저희 팀은 Firebase Distribution과 TestFlight 두 플랫폼을 모두 사용하기 때문에 배포 과정이 더욱 복잡했습니다.

이에 따라 반복적인 작업을 자동화해 팀 리소스를 최적화하고, 실수가 발생하지 않는 안정적인 배포 환경을 마련하기 위해 배포 자동화 프로젝트를 시작하게 되었습니다.

Fastlane 인터페이스 설계

우선 배포 자동화의 핵심이 될 Fastlane의 인터페이스를 설계했습니다. 프롬 서비스는 팬앱과 아티앱 두 가지 앱을 운영하고 있기 때문에 이를 모두 지원해야 했고, 또한 개발/QA/스테이지/프로덕션 환경을 구분해 배포할 수 있도록 구성했습니다.

# Fastlane CICD Interface

# Firebase Distribution 업로드
lane :upload_firebase do |options|
  # Parameters:
  # - app_type: fan/arti
  # - environment: dev/qa/stg/prd
  # - version: 앱 버전
  # - build_number: 빌드 번호
  # - release_notes: 릴리즈 노트
end

# TestFlight 업로드
lane :upload_testflight do |options|
  # Parameters:
  # - app_type: fan/arti
  # - version: 앱 버전
  # - build_number: 빌드 번호
  # TestFlight는 프로덕션 환경만 업로드하며,
  # 릴리즈 노트는 별도로 관리하기 때문에 파라미터에서 제외
end

Firebase Distribution 업로드와 TestFlight 업로드, 이렇게 2개의 public lane으로 인터페이스를 구성했습니다. TestFlight의 경우 프로덕션 환경만 업로드하고 릴리즈 노트도 App Store Connect에서 별도로 관리하기 때문에 파라미터를 최소화했습니다.

Fastlane 구현

Fastfile에서는 환경별로 적절한 configuration과 스키마를 매핑하고, Firebase Distribution의 경우 테스터 그룹도 환경별로 구분해서 관리하도록 했습니다.

def environment_to_configuration(environment)
  case environment
  when "dev"
    CONFIGURATION_DEV    # SandboxRelease
  when "qa"
    CONFIGURATION_QA     # QARelease
  when "stg"
    CONFIGURATION_STG    # StageRelease
  when "prd"
    CONFIGURATION_PRD    # StoreRelease
  else
    UI.user_error!("Invalid environment: #{environment}")
  end
end

# Firebase 테스터 그룹 환경별 매핑
def tester_group_by_configuration(configuration)
    case configuration
    when CONFIGURATION_DEV
      tester_groups = FIREBASE_TESTER_GROUPS_DEV      # "fromm-개발팀, fromm-기획팀, ..."
    when CONFIGURATION_QA
      tester_groups = FIREBASE_TESTER_GROUPS_QA
    when CONFIGURATION_STG
      tester_groups = FIREBASE_TESTER_GROUPS_STG
    when CONFIGURATION_PRD
      tester_groups = FIREBASE_TESTER_GROUPS_PRD
    end
end

Firebase Distribution과 TestFlight에서 공통으로 사용하는 update_version, build_fromm_app 등의 함수를 추가하여 아래와 같이 lane을 완성하였습니다!

lane :upload_firebase do |options|
    puts options
    
    app_type = options[:app_type]
    app_type_string = app_type == "fan" ? "팬앱" : "아티앱"
    environment = options[:environment]
    version = options[:version]
    build_number = options[:build_number]
    release_notes = options[:release_notes] || "#{app_type_string} #{version}(#{build_number}) #{environment} 환경 배포입니다."
    is_fan = app_type == "fan"
    configuration = environment_to_configuration(environment)
    tester_group = tester_group_by_configuration(configuration)
    
    update_version(
        isFan: is_fan,
        version_number: version,
        build_number: build_number,
        bump_build_number: false
    )
    
    build_fromm_app(
        configuration: configuration,
        is_fan: is_fan,
        distribution_service: DISTRIBUTON_SERVICE_FIREBASE
    )
    
    firebase_app_distribution(
        app: app_id,
        service_credentials_file: "./keystore/fastlane-firebase.json",
        ipa_path: ipa_absolute_path,
        release_notes: release_notes,
        groups: tester_groups,
        debug: true
    )
end

GitHub Actions와 난관들

Fastlane을 로컬에서 실행할 수도 있지만, 더 일관되고 안정적인 환경을 구성하기 위해 GitHub Actions를 활용하기로 했습니다. 처음에는 당연히 GitHub에서 제공하는 최신 macOS Runner를 사용하려고 했죠.

jobs:
  distribute-firebase:
    name: Distribute to Firebase
    runs-on: macos-latest

여기서 첫 번째 문제가 발생했습니다. 저희 프로젝트는 Tuist를 사용하기 때문에, GitHub에서 클론한 뒤 xcworkspace를 직접 generate해야 했습니다. 이를 위해 mise와 tuist가 정상 동작하도록 버전을 맞추고 workflow를 설정하는 과정에서 꽤 많은 어려움을 겪었습니다.

그런데 더 큰 난관이 기다리고 있었습니다. 바로 코드 사이닝과 빌드 시간 문제였습니다.

GitHub-hosted Runner의 한계

아카이브를 해서 Firebase든 TestFlight든 배포 사이트에 올리려면 인증서와 프로비저닝 파일이 필요한데, 독립된 환경에서 이 프로비저닝 파일을 세팅하는 것이 어려웠습니다.

기존에 Auto Signing을 사용하고 있었기 때문에 App Store Connect에 초대된 Apple 계정이 필요한 상황이었죠.

팀 계정을 사용해 workflow내에서 로그인을 하거나 fastlane match를 사용하는 방식을 고려해보았는데요, 다음의 이유로 아예 다른 방식으로 모든 문제를 해결하게 되었습니다.

바로 빌드에 소요되는 시간이었습니다. GitHub Runner의 성능이 좋지 않았는지, 아카이브가 너무너무 오래 걸렸습니다.

이에 따라 총 workflow 실행시간은 거의 40분 이상이 소요되었습니다. 수동으로 배포할 때도 10~20분 정도가 걸리는데, 자동화가 된다 하더라도 수동 배포보다 훨씬 오래 걸린다면 배포 프로세스에 적용하기가 곤란했습니다.

Self-hosted Runner로의 전환

이런 문제들 때문에 로컬 머신 활용한 self-hosted runner를 이용하기로 결정했습니다. 빌드하기 위한 맥북 2개를 할당받았고, 이를 GitHub Actions runner에 등록했습니다.

해당 맥북에는 미리 다음과 같은 환경을 세팅해두었습니다:

• Tuist 설치: 프로젝트 generate를 위해
• 올바른 버전의 Xcode 설치: 일관된 빌드 환경을 위해
• Xcode에 팀 공용 계정 등록: 팀 계정으로 사이닝 설정 (Auto Signing 사용 가능)

그리고 workflow에서는 특정 Xcode 버전을 사용하도록 명시적으로 선택하는 과정도 포함했습니다:

XCODE_PATH = "/Applications/Xcode-16.4.0.app"

# Fastlane에서 Xcode 버전 지정
xcode_select(XCODE_PATH)

jobs:
  distribute-firebase:
    name: Distribute to Firebase
    runs-on: self-hosted  # 이제 우리 맥북에서 실행!

workflow 실행 시간도 대폭 감소되어 10분 내외가 되었습니다.

self-hosted runner를 통해 다양한 환경 설정 문제와 빌드 시간 문제를 한번에 해결할 수 있었습니다!

GitHub Secret으로 인증 관리

Firebase와 TestFlight에 필요한 여러 인증서들을 GitHub Secret에 저장해두었습니다. 특히 JSON 키 파일같은 경우는 개행이 포함되면 GitHub workflow에서 오류가 발생할 수 있기 때문에 base64로 인코딩해서 사용했습니다.

- name: Generate key file
  run: |
    mkdir -p keystore
    echo '${{ secrets.FIREBASE_SERVICE_ACCOUNT_KEY }}' | base64 -d > ./keystore/fastlane-firebase.json

Firebase Distribution을 위한 환경변수들도 workflow에서 동적으로 생성하도록 구성했습니다:

- name: Make Fastlane Env
  run: |
    echo FIREBASE_FAN_APP_ID=${{ secrets.FIREBASE_FAN_APP_ID }} >> ./Fastlane/.env
    echo FIREBASE_STAR_APP_ID=${{ secrets.FIREBASE_STAR_APP_ID }} >> ./Fastlane/.env

실제 배포 과정은 Tuist로 프로젝트를 generate하고 Fastlane을 실행하는 단계로 구성되어 있습니다:

- name: Make .xcodeproj file
  run: |
      tuist install
      TUIST_ROOT_DIR=${PWD} tuist generate --no-binary-cache --verbose

      # Verify project files were generated
      echo "Checking generated project files..."
      ls -la *.xcworkspace *.xcodeproj 2>/dev/null || echo "No workspace/project files found at root"
      find . -name "*.xcworkspace" -o -name "*.xcodeproj" | head -5

- name: Run Fastlane
  run: fastlane upload_firebase app_type:${{ inputs.type }} environment:${{ inputs.environment }} version:${{ inputs.version_number }} build_number:${{ inputs.build_number }} release_notes:"${{ inputs.releaseNote }}"

빌드 머신 가용성 확보

언제든 가용성 있게 빌드 머신을 사용할 수 있도록 Amphetamine 앱을 설치해 맥북이 슬립 모드로 들어가지 않고 온라인 상태가 유지되도록 하였습니다.

그리고 Chrome 원격 데스크탑 확장 프로그램을 이용해 어디서든 문제 해결을 할 수 있도록 세팅했습니다.

다만 기기를 완전히 닫으면 슬립 모드가 되고 네트워크가 유실되므로 이 부분은 주의하도록 안내했습니다.

자동 버전 관리

추가적으로 Actions에서 배포가 성공하면 버전업 커밋을 자동으로 올리도록 구성했습니다.

- name: Auto commit version changes
  if: success()
  run: |
    git config --global user.name "GitHub Actions"
    git config --global user.email "actions@github.com"

    git add XCConfig/Artist/ArtistBase.xcconfig XCConfig/Fan/FanBase.xcconfig
    git commit -m "[version-up] ${{ inputs.version_number }}(${{ inputs.build_number }})"
    git push

이제 배포가 성공하면 xcconfig 파일의 버전 정보가 자동으로 업데이트되고, 커밋까지 올라가서 버전 히스토리를 깔끔하게 관리할 수 있게 되었습니다.

workflow_dispatch로 편리한 GUI 배포

workflow_dispatch를 이용해서 GUI 환경에서 편하게 배포할 수 있게 되었습니다. GitHub의 Actions 탭에서 버튼 클릭만으로 배포할 수 있고, 모바일에서도 사용 가능해서 정말 편리합니다.

on:
  workflow_dispatch:
    inputs:
      type:
        description: App Type (arti, fan)
        required: true
      environment:
        description: Server Environment (dev, qa, stg, prd)
        required: true
      version_number:
        description: Version Number (e.g. 1.2.3)
        required: true
      build_number:
        description: Build Number (e.g. 100)
        required: true
      releaseNote:
        description: Release Note
        required: true

GitHub 앱을 설치하면 모바일에서도 Actions를 실행할 수 있어서, 언제 어디서든 배포할 수 있게 되었습니다.

Slack 알림으로 완벽 마무리

배포 성공 시 Slack으로 알림을 보내도록 구성해서 팀원들이 실시간으로 배포 현황을 파악할 수 있도록 했습니다. Steve Jobs와 Tim Cook 아이콘으로 Firebase Distribution과 TestFlight를 구분해서 알림을 보내는 것도 소소한 재미 요소입니다.

# in Fastfile
SLACK_USERNAME = distribution_service == DISTRIBUTON_SERVICE_TESTFLIGHT ? SLACK_USERNAME_TIM : SLACK_USERNAME_STEVE
ICON_URL = distribution_service == DISTRIBUTON_SERVICE_TESTFLIGHT ? ICON_URL_TIM : ICON_URL_STEVE

slack(
    message: message,
    slack_url: DEPLOY_NOTY_SLACK_URL,
    username: SLACK_USERNAME,
    icon_url: ICON_URL,
    default_payloads: [],
    attachment_properties: {
        fields: fields
    },
    fail_on_error: false,
    link_names: true
)

마치며

이렇게 해서 저희는 iOS 배포 자동화에 성공했습니다! 이제 더 이상 번거로운 수동 배포 과정을 반복할 필요가 없어졌고, 실수할 가능성도 크게 줄어들었습니다.

특히 GitHub Actions의 workflow_dispatch를 활용한 GUI 기반 배포는 정말 만족스러운 결과였습니다. 몇 번의 클릭만으로 원하는 환경에 원하는 버전을 배포할 수 있고, 모바일에서도 가능하다는 점이 큰 장점이었습니다.

물론 self-hosted runner를 사용하면서 빌드 머신 관리라는 새로운 과제가 생겼지만, 그보다는 얻은 것이 훨씬 많다고 생각합니다. 빌드 속도도 빨라졌고, 많은 문제들이 깔끔하게 해결되었습니다.

앞으로는 이 자동화된 배포 시스템을 통해 더 빠르고 안정적으로 프롬 서비스를 개선해 나가도록 하겠습니다. 감사합니다!