Fastlane iOS 연동

AppSealing SDK는 Fastlane을 적용한 프로젝트에서도 사용할 수 있습니다. 일반적으로 Xcode 프로젝트에서 Fastlane 도구를 사용하는 이유는 앱 빌드 및 패키징 프로세스를 자동화하고, 이후 배포 프로세스도 자동화하기 위해서입니다. Xcode 프로젝트에 AppSealing SDK를 적용할 경우 앱 빌드 후 추가 단계가 필요하지만, Fastlane이 적용된 경우 Fastfile 스크립트에 AppSealing 애플리케이션 프로세스를 추가함으로써 기존 자동화 프로세스를 유지할 수 있습니다. 이 장에서는 Fastlane의 자동화된 빌드 및 배포 프로세스를 유지하기 위해 스크립트를 수정하는 방법을 설명합니다.

📋프로젝트 Fastfile 구성

다음은 Fastlane이 활성화된 “TestApp_Swift” 프로젝트의 Fastfile 코드입니다(주석 제외). 이 코드에는 앱을 빌드하고 서명하며 Testflight에 업로드하는 단계가 포함되어 있습니다. Apple Store에 업로드하는 스크립트는 동일한 구조를 갖기 때문에, 이 가이드에서는 Testflight 사례만 설명합니다.

🔐 Fastfile 기본값

default_platform(:ios)
  platform :ios do
  desc "Push a new beta build to TestFlight"
  lane :beta do
      increment_build_number(xcodeproj: "TestApp_Swift.xcodeproj")
      build_app(scheme: "TestApp_Swift")
      upload_to_testflight
  end
end

일반적으로 이 파일을 크게 수정하지 않고 “fastlane beta” 명령어를 실행하여 빌드 및 배포를 수행합니다. 여기에서 AppSealing SDK를 적용하려면 빌드와 배포 사이에 추가 작업이 필요하므로, fastfile 스크립트를 다음과 같이 수정해야 합니다. 원본 스크립트에서는 프로젝트 이름과 파일 이름이 직접 문자열 값으로 입력되지만, 수정할 스크립트는 프로젝트 폴더에서 필요한 값을 추출하도록 설계되어 있어 모든 다른 프로젝트에 적용할 수 있습니다. 따라서 프로젝트 이름이 “TestApp_Swift”가 아니더라도 동일한 Fastfile 스크립트를 모든 프로젝트에 적용할 수 있습니다.

텍스트 편집기로 Fastfile을 열고 모든 코드를 “Fastlane Scripts/Fastfile” 파일의 코드로 교체하세요. 아래 코드에서 FASTLANE_USER, FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD, 및 PROFILE 값을 실제로 사용하는 값으로 교체해야 합니다. FASTLANE_USER는 귀하의 Apple 계정이며, FASTLANE_APPLE_APPLICATION_SPECIFIC_PASSWORD는 귀하의 앱 전용 비밀번호입니다. PROFILE 값은 배포 단계에서 사용하는 프로비저닝 프로파일의 이름이어야 합니다. 코드를 수정하고 이전과 같이 “fastlane beta” 명령어를 실행하면 앱을 빌드하고 IPA로 내보내며, generate_hash 스크립트를 자동으로 실행한 후 AppSealing이 활성화된 IPA를 TestFlight에 업로드합니다.

GitHub Actions와 Fastlane 동시 사용

Xcode 프로젝트 코드가 GitHub에 업로드되고 GitHub Actions를 통해 코드가 푸시될 때 자동으로 빌드 및 배포를 수행하는 배포 파이프라인을 구축할 수 있습니다. 이 경우, 아래와 같이 Action 정의에 YAML 형식의 빌드 스크립트 파일을 추가해야 합니다.

이 파일은 소스 코드 브랜치 이름을 “develop”로 정의하고, 프로젝트에 포함된 fastfile을 실행하기 위해 Fastlane 설치 단계를 포함합니다. 또한 env에 APP_STORE_CONNECT_KEY_ID, APP_STORE_CONNECT_ISSUER_ID, 및 APP_STORE_CONNECT_PRIVATE_KEY 값을 지정하여 fastfile을 실행하기 위해 필요한 환경 변수를 설정합니다. 로컬 프로젝트에 Fastlane을 적용하거나 Xcode Cloud를 사용할 때는 앱 전용 비밀번호를 사용했지만, 이 단계에서는 App Store Connect API를 사용합니다. App Store Connect API를 사용하려면 Apple 계정 페이지에서 API 키를 획득해야 하며, 여기서 발급된 개인 키(APP_STORE_CONNECT_PRIVATE_KEY), 키 ID(APP_STORE_CONNECT_KEY_ID), 및 발급자 ID(APP_STORE_CONNECT_ISSUER_ID)를 fastfile 스크립트에 전달해야 합니다. 실제 전달되는 값은 스크립트에 직접 입력되지 않으며, GitHub Action의 secrets 변수에 저장된 후 해당 변수를 참조하여 전달되는 방식으로 작성됩니다.

프로젝트의 기본 GitHub Action 빌드 스크립트 (ios_build.yml)

  name: iOS Build & Deploy
    on:
      push:
      branches:
        - develop
    jobs:
      release-ios:
        name: Build and release iOS app
        runs-on: macos-latest
        steps:
          - uses: actions/checkout@v2

          - uses: actions/setup-ruby@v1

          with:
            ruby-version: '3.1.2'

          - name: Install Fastlane
          run: cd ios && bundle install

          - name: Install pods
          run: cd ios && pod install

          - name: Execute Fastlane
            env:
              APP_STORE_CONNECT_KEY_ID: ${{ secrets.KEY_ID }}
              APP_STORE_CONNECT_API_KEY: ${{ secrets.API_KEY }}
              APP_STORE_CONNECT_PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
            run: cd ios && fastlane release

---

아래는 이러한 환경 변수를 사용하여 실제 fastlane 작업을 수행하는 Fastfile 코드입니다. 이 코드에는 App Store Connect API를 사용하기 위한 설정 단계와 앱을 빌드하고 업로드하는 단계가 포함되어 있습니다.

GitHub 프로젝트의 기본 Fastfile 스크립트

  default_platform(:ios)
  platform :ios do
    desc "Release to App Store"
    lane :release do
    # App Store Connect API Authentication
      app_store_connect_api_key(
        key_id: ENV["APP_STORE_CONNECT_KEY_ID"],
        issuer_id: ENV["APP_STORE_CONNECT_ISSUER_ID"],
      key_content: ENV["APP_STORE_CONNECT_PRIVATE_KEY"]
    )
      # build app
            build_app(
            scheme: "scheme_name_of_project",
            export_method: "app-store"
             )
        # upload app
        upload_to_testflight(
          skip_waiting_for_build_processing: true,
          distribute_external: true
        )
    end
  end

App Store Connect API 키를 아직 발급받지 않으셨다면, 이 링크를 참조하여 키를 발급받은 후 아래 단계로 진행해 주시기 바랍니다.

AppSealing SDK를 이 상태에서 적용할 경우 다음과 같은 조치를 취해야 합니다. AppSealing SDK를 적용하면 아카이브 및 수출 단계에서 생성된 IPA에 스크립트 작업을 수행해야 하며, 이 과정에서 IPA가 재서명되므로 추가 서명 인증서와 프로비저닝 프로파일이 필요합니다.

인증서는 스토어 업로드용 배포 인증서여야 하며, 프로파일도 배포 프로파일이어야 합니다. 따라서 인증서를 PKCS#12 형식으로 변환하여 프로젝트에 포함시키고, 프로비저닝 프로필과 함께 GitHub에 푸시해야 합니다. 이 때 인증서의 파일 이름은 “certificate.p12”이며, 프로비저닝 프로필의 파일 이름은 “distribution.mobileprovision”이어야 합니다.

다른 파일 이름을 사용한다면, 아래 스크립트에서 해당 파일 이름을 적절히 수정해야 합니다. 프로비저닝 프로파일의 이름은 PROFILE 환경 변수에 직접 값을 입력하여 수정할 수 있습니다. PKCS#12 형식으로 인증서를 저장할 때 비밀번호는 “123456”로 설정되어 있다고 가정됩니다. 비밀번호가 다를 경우, 아래 스크립트에서 비밀번호 문자열도 수정해야 합니다. SDK의 “Fastlane Scripts/Fastfile_GithubAction” 파일의 내용을 사용하여 “ios_build.yml” 스크립트를 수정하여 GitHub에 업로드된 인증서를 키체인에 설치하고 프로비저닝 프로파일을 설치합니다.

이 스크립트에는 “runs-on: macos-15” 및 “xcode-version: ’16.0’”이 포함되어 있습니다. 이는 Xcode 16부터 프로비저닝 프로파일 저장 경로가 변경되었기 때문입니다. Xcode 버전 16을 지정하지 않으면 프로파일이 잘못된 경로로 복사되어 IPA 후처리 단계에서 재서명 과정이 실패할 수 있습니다.

이제 앱을 빌드하고 재서명하며 업로드하는 작업이 AppSealing SDK와 관련된 작업과 일치하도록 하기 위해, SDK의 “Fastlane Scripts/Fastfile_GithubAction” 파일의 내용을 Fastfile에 반영해야 합니다.

이 스크립트는 App Store Connect에서 앱 정보를 가져오는 것부터 빌드 번호를 자동으로 증가시키고, 앱을 빌드하며, IPA로 내보내고, generate_hash 스크립트를 적용하고, 재서명하며, App Store Connect에 업로드하는 전체 과정을 포함합니다. 이 프로세스에 필요한 모든 값(예: 프로젝트 이름, 스키마, 타겟, 번들 ID)은 프로젝트 파일에서 자동으로 추출되어 사용되므로, TestApp_Swift 이외의 프로젝트에도 동일한 스크립트를 사용할 수 있습니다.