fastlane 자동 빌드: 2026 원격 맥 배포 안내
이 글은 로컬 맥이 없는 독립 개발자가 원격 맥을 iOS 배포 서버로 바꾸는 과정을 설명합니다. fastlane 설치부터 코드 서명, 아카이브, App Store Connect 업로드, 장기 운영과 실패 복구까지 실제 배포 순서에 맞춰 정리했습니다.
목차
- 실패한 배포에서 먼저 확인해야 할 네 가지 상태
- 배포 전 원격 맥과 애플 계정을 점검합니다
- 첫 시간에는 fastlane 버전과 프로젝트 경로를 고정합니다
- 자동 서명과 match는 프로젝트 규모에 따라 나눕니다
- TestFlight 업로드는 API 키로 분리해서 검증합니다
- 첫 주에는 단일 명령을 복구 가능한 배포 흐름으로 바꿉니다
- 단계별 합격 기준으로 실제 배포를 검수합니다
- 자주 막히는 상황을 배포 순서대로 해결합니다
- 로컬 맥이 없어도 iOS 앱을 fastlane으로 빌드할 수 있나요
- 원격 맥에서 TestFlight 자동 업로드는 어떻게 구성하나요
- 자동 서명은 match와 Xcode 중 무엇이 낫나요
- API Key를 배포 서버에 안전하게 넣으려면 어떻게 하나요
- 빌드는 성공했는데 App Store Connect 업로드가 실패하면 어떻게 하나요
fastlane 자동 빌드는 처음부터 심사 제출까지 한 번에 자동화하지 말고, 원격 맥에서 빌드, 서명, 업로드, 자격 증명 복구를 차례로 검증한 뒤 자동 제출을 추가하는 방식이 안전합니다. 이번 주에는 먼저 TestFlight에 정상적으로 보이는 빌드 하나를 만드는 것을 목표로 잡으세요.
이 글은 로컬 맥이 없는 Windows 또는 Linux 개발자에게 적합합니다. 이미 수동 배포가 가능하지만 인증서와 프로비저닝 프로파일 때문에 자주 멈추는 개발자, 원격 맥을 상시 iOS 배포 서버로 운영하려는 소규모 팀도 대상입니다.
실패한 배포에서 먼저 확인해야 할 네 가지 상태
빌드가 끝났다는 메시지만 보고 성공으로 판단하면 안 됩니다. 실제 배포는 다음 네 상태로 나눠서 확인해야 합니다.
- 빌드 성공: Xcode가 프로젝트를 컴파일하고 아카이브를 만들었습니다.
- 서명 성공: 앱 번들의 식별자와 인증서, 프로비저닝 프로파일이 일치합니다.
- 업로드 성공: 생성된 파일이 App Store Connect로 전송되었습니다.
- 처리 및 제출 가능: App Store Connect가 빌드를 처리했고 TestFlight 또는 심사 버전에 연결할 수 있습니다.
Apple은 업로드한 빌드가 처리된 뒤에야 App Store Connect에서 사용할 수 있다고 안내합니다. 따라서 fastlane 명령이 종료 코드 0을 반환했더라도, 화면에서 빌드가 처리 중인지 실패했는지 별도로 확인해야 합니다. Apple의 빌드 업로드 안내에서도 이 처리 단계를 별도 과정으로 설명합니다.
처음부터 자동 심사 제출까지 연결하면 원인 분리가 어려워집니다. 특히 서명 오류와 메타데이터 오류가 동시에 발생하면 로그만으로 어느 단계가 문제인지 판단하기 어렵습니다.
배포 전 원격 맥과 애플 계정을 점검합니다
원격 맥은 단순히 fastlane을 설치하는 컴퓨터가 아닙니다. Xcode, macOS, 프로젝트 의존성, 키체인, 네트워크, 저장 공간이 함께 맞아야 합니다.
Apple의 공식 시스템 요구 사항 표를 먼저 확인하세요. 현재 Xcode 26.6은 macOS Tahoe 26.2 이상을 요구하며, iOS 26.5 SDK를 포함합니다. 프로젝트가 사용하는 SDK와 배포 대상이 설치된 Xcode에서 실제로 지원되는지도 확인해야 합니다. Apple의 Xcode 시스템 요구 사항을 기준으로 점검하세요.
2026년부터 App Store Connect 업로드에는 Xcode 14 이상이 필요합니다. 다만 이것은 업로드 도구의 최소 조건일 뿐이며, iOS 앱을 어떤 SDK로 빌드할 수 있는지는 대상별 지원 버전에 따라 달라집니다. Apple의 지원 Xcode 버전 표를 프로젝트의 기준으로 사용하세요.
| 점검 항목 | 확인할 내용 | 실패했을 때의 증상 |
|---|---|---|
| Xcode와 macOS | 프로젝트 SDK와 호환되는 설치 조합인지 확인합니다 | 빌드 도구 또는 SDK 오류가 발생합니다 |
| 프로젝트 식별자 | Bundle ID와 App Store Connect 앱 기록이 같은지 확인합니다 | 업로드 후 다른 앱으로 인식되거나 연결되지 않습니다 |
| 저장소 | Git에서 고정된 커밋을 내려받는지 확인합니다 | 원격 맥마다 코드와 설정이 달라집니다 |
| 접근 권한 | SSH는 명령 실행, 그래픽 콘솔은 Xcode와 키체인 확인에 사용합니다 | 서명 팝업이나 키체인 잠금으로 작업이 멈춥니다 |
| 관리자 권한 | root 권한은 설치와 환경 복구에만 제한적으로 사용합니다 | 파일 소유권이 꼬여 다음 실행이 실패할 수 있습니다 |
원격 맥을 새로 준비한다면 VPSMAC의 서울 원격 맥 환경처럼 접속 방식과 관리자 권한 범위를 먼저 확인하세요. SSH만 가능한지, VNC나 웹 콘솔로 키체인을 확인할 수 있는지에 따라 초기 설정 난도가 달라집니다.
첫 시간에는 fastlane 버전과 프로젝트 경로를 고정합니다
fastlane을 전역으로 설치하고 바로 실행하는 방법은 빠르지만, 장기 운영에는 불리합니다. Ruby와 fastlane 의존성이 바뀌면 같은 저장소가 다른 결과를 낼 수 있기 때문입니다.
fastlane 공식 문서는 Bundler와 Gemfile로 버전을 관리하고, Gemfile.lock을 저장소에 함께 보관하는 방식을 권장합니다. fastlane iOS 설정 문서에 나온 흐름대로 다음 작업을 진행하세요.
xcode-select --install
gem install bundler
cat > Gemfile <<'EOF'
source "https://rubygems.org"
gem "fastlane"
EOF
bundle install
bundle exec fastlane init
Gemfile, Gemfile.lock, Fastfile, Appfile은 프로젝트 저장소에 포함합니다. 단, API 키 파일과 개인 키는 저장소에 넣지 않습니다.
fastlane init 이후에는 다음 사실을 직접 확인하세요.
.xcworkspace를 사용하는지.xcodeproj를 사용하는지 확인합니다.- 실제 배포용 scheme이 공유 상태인지 확인합니다.
- Release 설정이 올바른 signing 설정을 사용하는지 확인합니다.
- 앱의 Bundle ID가 App Store Connect 기록과 일치하는지 확인합니다.
- 프로젝트가 요구하는 환경 변수와 외부 의존성을 문서화합니다.
처음부터 업로드하는 Lane을 만들지 말고, 먼저 아카이브만 생성하는 Lane을 작성합니다.
default_platform(:ios)
platform :ios do
lane :archive_only do
build_app(
workspace: "YOUR_APP.xcworkspace",
scheme: "YOUR_SCHEME",
configuration: "Release",
clean: true,
output_directory: "./build"
)
end
end
실행 명령은 다음과 같습니다.
bundle exec fastlane archive_only
fastlane의 build_app 문서에 따르면 이 작업은 설정된 scheme으로 앱을 빌드하고 배포용 산출물을 생성합니다. 이 단계에서는 업로드하지 말고 전체 로그와 생성 파일 경로를 보관하세요.
자동 서명과 match는 프로젝트 규모에 따라 나눕니다
단일 개발자가 하나의 앱을 관리하고 Xcode 프로젝트의 자동 서명이 안정적으로 작동한다면 Xcode 자동 서명으로 시작할 수 있습니다. 반대로 여러 개발자, 여러 환경, 여러 앱을 지속적으로 빌드한다면 서명 자산을 중앙에서 관리하는 match가 더 적합합니다.
| 선택지 | 적합한 상황 | 장점 | 주의할 점 | 평가 |
|---|---|---|---|---|
| Xcode 자동 서명 | 개인 프로젝트, 환경 수가 적은 경우 | 초기 설정이 단순합니다 | CI에서 새 자산을 만들거나 변경할 수 있습니다 | 시작 난도 5점 |
match |
팀 프로젝트, 반복 배포, 여러 앱 | 인증서와 프로파일을 정해진 방식으로 동기화합니다 | 저장소와 복호화 비밀 관리가 필요합니다 | 운영성 5점 |
| 혼합 방식 | 기존 자산은 유지하고 새 환경만 검증하는 경우 | 전환 위험을 줄일 수 있습니다 | 어떤 Lane이 어떤 자산을 쓰는지 문서화해야 합니다 | 전환성 4점 |
자동화 서버에서는 기존 인증서와 프로파일을 읽기 전용으로 가져오는 흐름을 우선하세요. 무인 작업이 만료된 자산을 발견할 때마다 새 인증서를 만들도록 두면, 팀의 서명 자산이 예상하지 못한 방식으로 바뀔 수 있습니다.
match를 사용한다면 저장소 접근용 비밀과 암호 해제 비밀을 따로 관리합니다. fastlane은 match를 통해 코드 서명 자산을 설치할 수 있다고 설명하지만, 어떤 자산을 만들거나 갱신할지는 프로젝트 운영 정책으로 제한해야 합니다. fastlane의 match 문서를 참고하세요.
TestFlight 업로드는 API 키로 분리해서 검증합니다
App Store Connect API Key는 키 식별자, 발급자 식별자, 개인 키 파일로 구성됩니다. 개인 키 파일은 생성 뒤 다시 내려받을 수 없으므로 원격 맥의 저장소가 아니라 비밀 저장소나 접근 제한 디렉터리에 보관해야 합니다.
Apple은 API 키에 역할 권한을 부여하며, 팀 키는 모든 앱에 적용될 수 있다고 설명합니다. 따라서 처음에는 배포에 필요한 최소 역할을 선택하고, 관리자 권한을 그대로 넣지 않는 편이 안전합니다. Apple의 API Key 생성 문서를 함께 확인하세요.
예시 파일에는 실제 값을 넣지 않습니다.
{
"key_id": "YOUR_KEY_ID",
"issuer_id": "YOUR_ISSUER_ID",
"key": "YOUR_PRIVATE_KEY_CONTENT"
}
권장 Lane은 아카이브와 업로드를 분리하거나, 최소한 업로드를 별도 이름으로 구분하는 방식입니다.
platform :ios do
lane :upload_testflight do
api_key = app_store_connect_api_key(
key_id: ENV["ASC_KEY_ID"],
issuer_id: ENV["ASC_ISSUER_ID"],
key_filepath: ENV["ASC_KEY_PATH"]
)
upload_to_testflight(
api_key: api_key,
ipa: "./build/YOUR_APP.ipa",
skip_waiting_for_build_processing: true
)
end
end
fastlane은 API Key 인증을 지원하며 upload_to_testflight에 키 정보를 전달할 수 있습니다. fastlane의 App Store Connect API 문서와 TestFlight 업로드 문서에서 지원 방식과 매개변수를 확인하세요.
처음에는 자동 제출 옵션을 켜지 마세요. TestFlight에 빌드가 보이는지 확인한 뒤, App Store Connect에서 빌드가 처리되고 앱 버전에 연결되는지 검토합니다. 심사 제출은 이 확인 이후 별도 Lane으로 추가하는 것이 좋습니다. Apple은 한 앱 버전에 연결할 빌드를 선택한 뒤 심사 제출을 진행하도록 안내합니다. 빌드 선택 및 제출 절차를 기준으로 확인하세요.
첫 주에는 단일 명령을 복구 가능한 배포 흐름으로 바꿉니다
첫 실행이 성공하면 다음 순서로 장기 운영 요소를 추가합니다.
- 원격 맥에서 Git 저장소를 가져오고 배포 대상 커밋을 기록합니다.
bundle install로Gemfile.lock에 맞는 의존성을 설치합니다.xcode-select -p와xcodebuild -version으로 선택된 Xcode를 기록합니다.- 키체인이 잠겨 있지 않은지 확인하고 서명 자산의 유효성을 검사합니다.
- 현재 빌드 번호를 확인한 뒤 중복되지 않는 번호를 설정합니다.
build_app으로 Archive와 IPA를 생성합니다.- IPA 경로, Bundle ID, 버전, 빌드 번호, 서명 정보를 로그에 남깁니다.
- TestFlight 업로드를 실행하고 App Store Connect 처리 상태를 확인합니다.
- 실패 시 전체 로그와 커밋 식별자를 보존한 뒤 원인을 수정합니다.
다음 항목은 실행 전 검사로 두는 것이 좋습니다.
set -e
test -d "YOUR_APP.xcworkspace"
test -n "$ASC_KEY_ID"
test -n "$ASC_ISSUER_ID"
test -f "$ASC_KEY_PATH"
xcode-select -p
xcodebuild -version
bundle check || bundle install
set -e는 중간 명령이 실패했는데도 다음 단계로 진행하는 문제를 줄입니다. 다만 업로드가 네트워크 오류로 중단됐다고 무조건 다시 실행하면 안 됩니다. Apple 서버에 이미 파일이 전달됐는지 먼저 Delivery 로그와 App Store Connect의 빌드 목록을 확인하세요.
안전하게 재시도할 수 있는 작업과 주의해야 할 작업을 구분해야 합니다.
- 의존성 설치 실패는 환경을 정리한 뒤 다시 실행할 수 있습니다.
- Xcode 아카이브 실패는 로그와 프로젝트 설정을 수정한 뒤 재실행합니다.
- 업로드 중단은 빌드가 서버에 등록됐는지 먼저 확인합니다.
- 빌드 번호 변경은 이미 사용된 번호와 겹치지 않는지 확인합니다.
- 심사 제출은 중복 제출을 피하기 위해 수동 승인 단계로 남겨두는 편이 안전합니다.
단계별 합격 기준으로 실제 배포를 검수합니다
아래 표를 문서에 복사해 배포마다 기록하세요. 단순히 명령이 끝났는지가 아니라 결과물이 다음 단계에서 사용할 수 있는지를 확인하는 방식입니다.
| 단계 | 합격 조건 | 남겨야 할 기록 | 실패 시 우선 확인 |
|---|---|---|---|
| 환경 | 올바른 Xcode와 프로젝트 경로가 선택됨 | Xcode 버전, Git 커밋 | xcode-select, scheme |
| 빌드 | Archive와 IPA가 생성됨 | 산출물 경로, 버전, 빌드 번호 | workspace, scheme, Release 설정 |
| 서명 | Bundle ID와 서명 자산이 일치함 | 서명 검사 결과 | 키체인, 프로파일, 인증서 |
| 업로드 | App Store Connect 전달 로그가 성공함 | fastlane 로그, 전달 식별 정보 | API Key 역할, 네트워크 |
| 처리 | TestFlight에서 빌드가 선택 가능함 | 처리 상태, 오류 메시지 | 처리 대기, 암호화 문항 |
| 제출 | 선택한 빌드와 앱 버전이 일치함 | 제출 시각과 버전 | 잘못된 빌드 연결 여부 |
이 검수는 성능 수치를 비교하는 테스트가 아닙니다. 배포 서버의 가치는 특정 시간 안에 끝나는지보다, 실패했을 때 어느 단계에서 멈췄는지 다시 확인할 수 있는지에 있습니다.
자주 막히는 상황을 배포 순서대로 해결합니다
로컬 맥이 없어도 iOS 앱을 fastlane으로 빌드할 수 있나요
가능합니다. fastlane은 명령줄 도구이지만 iOS 빌드와 서명에는 macOS와 Xcode가 필요합니다. Windows나 Linux에서 코드를 작성하고, 원격 맥에 SSH로 접속해 bundle exec fastlane archive_only와 업로드 Lane을 실행하는 구성이 일반적입니다. fastlane 자체는 여러 환경에서 일부 동작할 수 있지만, iOS 배포에 필요한 Xcode 작업은 macOS에서 수행해야 합니다.
원격 맥에서 TestFlight 자동 업로드는 어떻게 구성하나요
먼저 아카이브 전용 Lane을 성공시킨 뒤 API Key를 연결합니다. 그 다음 upload_to_testflight를 별도 Lane으로 실행하고, App Store Connect에서 처리된 빌드가 실제로 보이는지 확인합니다. 자동 제출은 마지막에 추가해야 업로드 문제와 심사 메타데이터 문제를 분리할 수 있습니다.
자동 서명은 match와 Xcode 중 무엇이 낫나요
개인 프로젝트와 단일 배포 환경은 Xcode 자동 서명이 관리하기 쉽습니다. 팀원이 늘거나 여러 앱과 환경을 반복적으로 배포한다면 match가 유리합니다. 단, match를 도입한다고 해서 인증서 만료와 저장소 비밀 관리가 자동으로 해결되는 것은 아닙니다.
API Key를 배포 서버에 안전하게 넣으려면 어떻게 하나요
개인 키를 Git 저장소, Fastfile, 셸 명령 기록에 넣지 마세요. 환경 변수에는 경로와 식별자만 두고, 실제 .p8 파일은 접근 권한이 제한된 위치에 보관합니다. 키가 노출됐다고 의심되면 Apple 안내에 따라 즉시 폐기하고 새 키를 발급해야 합니다.
빌드는 성공했는데 App Store Connect 업로드가 실패하면 어떻게 하나요
먼저 IPA가 생성됐는지와 서명이 유효한지 확인합니다. 그 다음 API Key의 역할, 키 식별자, 발급자 식별자, 개인 키 경로를 확인합니다. 업로드가 중단된 경우에는 명령을 반복하기 전에 App Store Connect의 빌드 목록과 전달 로그에서 이미 등록된 빌드가 있는지 확인하세요. 등록은 됐지만 TestFlight에 보이지 않는다면 업로드 실패가 아니라 처리 대기일 수 있습니다.
현재 방식이 개인 컴퓨터에서 수동으로 실행하는 구조라면, 컴퓨터가 꺼져 있을 때 배포가 멈추고 Xcode 버전이 사람마다 달라지며 인증서와 로그가 한 사람의 환경에 묶이는 문제가 생깁니다. 반대로 장기간 무거운 빌드를 계속 실행하거나 실제 기기와 물리 장비가 꼭 필요한 경우에는 전용 장비를 직접 운영하는 편이 맞을 수 있습니다.
다만 정기 배포와 TestFlight 업로드가 목적이라면, 고정된 원격 macOS 환경에서 SSH와 그래픽 콘솔을 함께 사용하고, 로그와 권한을 직접 관리하는 구성이 더 예측 가능합니다. VPSMAC의 원격 맥 배포 환경을 검토할 때도 가격보다 먼저 고정 환경, 관리자 권한, 접속 방식, 로그 보존 여부를 확인한 뒤 이 글의 검수표로 실제 배포를 한 번 끝까지 실행해 보세요.