fastlane deliver App Store 업로드: API Key인가 Apple ID인가? 2026

fastlane deliver에서 API Key를 쓸 수 있는지는 먼저 확인할 항목입니다. 하지만 인증 성공이 게시 과정 전체의 성공을 뜻하지는 않습니다. 하나의 게시 파이프라인이라도 앱 정보 수정, 바이너리 업로드, TestFlight 배포처럼 서로 다른 작업이 이어질 수 있습니다.

fastlane은 App Store Connect API를 사용하는 기능과 도구별 지원 범위를 안내합니다. API Key가 모든 fastlane 도구를 지원하는 것은 아니므로, fastlane의 App Store Connect API 지원 안내에서 사용하는 action을 확인하세요. deliver의 옵션과 동작은 deliver 공식 문서에서도 대조할 수 있습니다.

작업을 구분하지 않으면 첫 단계에서 인증이 성공한 뒤 다음 action이 Apple ID를 요구하거나 필요한 권한이 부족해 게시가 멈출 수 있습니다. 따라서 fastlane 업로드 App Store 흐름을 한 덩어리로 보지 말고, 실제 실행 순서에 맞춰 인증과 권한을 따로 기록하세요.

App Store Connect API Key는 JWT 요청을 승인하는 데 쓰이며, Apple 문서는 Team Key와 Individual Key의 범위 및 역할을 구분합니다. Team Key는 개별 앱 하나에만 격리되는 키로 보면 안 됩니다. 키 종류와 사용자 역할을 실제 게시 업무에 필요한 범위에 맞추세요. Apple의 키 생성 및 권한 안내에서 키 유형과 접근 조건을 확인할 수 있습니다.

Apple은 API 요청용 JWT의 유효 기간에 상한을 둡니다. 토큰을 장기간 재사용하는 설계는 피하고, 생성 시점과 요청 흐름을 JWT 토큰 생성 규칙에 맞추세요.

빌드 업로드에 필요한 역할도 별도로 확인해야 합니다. 메타데이터를 수정할 수 있다는 사실만으로 빌드 업로드 권한까지 충분하다고 판단하지 마세요. Apple의 빌드 업로드 역할 안내와 현재 계정의 역할을 대조하세요.

API Key를 쓸 때는 Key ID와 Issuer ID, .p8 개인 키가 각각 필요한 정보입니다. 개인 키 파일은 저장소에 커밋하지 마세요. CI 비밀 변수나 접근이 제한된 파일 저장소에서 주입하고, 작업 로그에 값이 출력되지 않는지 확인하세요. Apple의 키 생성 절차도 개인 키 보관 책임을 다룹니다.

Apple ID를 사용하는 경우에도 계정 인증 정보를 일반 설정 파일이나 공유 문서에 넣어서는 안 됩니다. fastlane 인증 문서는 Apple ID, 이중 인증, 앱 전용 암호가 쓰이는 범위를 설명합니다. 앱 전용 암호를 메타데이터 관리 등 모든 App Store Connect 작업의 대체 인증으로 간주하지 말고, fastlane 인증 안내에서 해당 작업의 조건을 확인하세요.

작업자가 바뀌거나 CI 환경을 이전할 때는 키를 누가 만들었는지, 어디에 보관하는지, 누가 교체할 수 있는지 기록해야 합니다. 로그를 공유하기 전에는 환경 변수와 인증 오류 메시지에 민감한 값이 포함되지 않았는지도 살펴보세요.

API Key 지원 여부는 fastlane action에 따라 달라질 수 있습니다. deliver에서 API Key를 전달하는 설정을 사용할 수 있더라도, 같은 파이프라인에 추가한 다른 action까지 자동으로 지원된다고 볼 수 없습니다. TestFlight 배포나 추가 정보 제출을 포함한다면 각각의 공식 문서에서 인증 인자를 확인하세요.

권한 오류가 나면 다음 순서로 원인을 좁히세요.

• 키 유형과 해당 키에 연결된 역할이 의도한 계정과 맞는지 확인합니다.
• 실행 중인 fastlane action이 API Key 인증을 지원하는지 확인합니다.
• 메타데이터 수정과 빌드 업로드에 필요한 역할을 각각 점검합니다.
• 환경 변수가 실제 실행 환경에 전달되는지 확인합니다.
• 로그를 검토하되 개인 키나 인증 정보를 출력하지 않도록 합니다.

API Key가 지원되지 않는 작업이라면 그 단계에 한해서 Apple ID 인증을 유지하는 방안을 검토하세요. fastlane 문서의 인증 지원 범위와 개별 action의 최신 설명이 다르게 보이면 해당 작업 문서를 기준으로 재확인해야 합니다.

fastlane deliver에서 API Key를 쓸 수 있나요?

사용할 수 있습니다. 다만 deliver가 실행하는 세부 작업과 함께 쓰는 다른 action의 지원 범위까지 확인해야 합니다. fastlane 공식 지원 안내와 deliver 문서에서 현재 구성에 해당하는 인증 옵션을 살펴보세요. 테스트용 작업에서 인증, 메타데이터 변경, 업로드를 각각 실행하면 어느 단계가 키를 사용하는지 구분할 수 있습니다.

빌드 업로드에는 언제 Apple ID가 필요할 수 있나요?

게시 흐름의 모든 작업이 동일한 인증 방식을 지원하는 것은 아닙니다. API Key 미지원 작업이 포함되어 있거나 필요한 역할이 맞지 않는 경우에는 해당 단계에서 다른 인증이 필요할 수 있습니다. 업로드 작업과 메타데이터 작업을 분리해 권한을 확인하고, fastlane action 문서 및 Apple의 업로드 역할 안내를 함께 대조하세요.

원격 맥에서 자동 게시할 때 어떤 인증을 먼저 검토해야 하나요?

사용하는 작업이 지원하고 필요한 권한을 부여할 수 있다면 API Key를 먼저 검토하세요. Apple ID의 대화형 인증 의존도를 낮출 수 있지만, 개인 키 보관과 실행 환경의 접근 통제는 여전히 필요합니다. 작업 일부가 API Key를 지원하지 않는 경우에는 그 단계에 한해 Apple ID를 유지하고, 비공식 게시 작업으로 전체 흐름을 검증하세요.

API Key 권한이 부족할 때 앱 단위 키를 새로 만들면 해결되나요?

항상 그렇지는 않습니다. Team Key를 앱 하나에만 제한할 수 있다고 가정하지 마세요. 먼저 키 종류와 연결된 역할, 실패한 action의 지원 범위를 확인해야 합니다. 앱별 접근 범위가 필요한 상황이라면 Apple 문서에서 Individual Key의 조건을 확인하고, 팀의 계정 구조 및 게시 작업에 맞는지 검토하세요.

게시 상태는 인증, 전송, App Store Connect 처리, TestFlight 또는 심사 상태로 나눠 확인해야 합니다. fastlane이 인증을 마쳤다는 메시지는 바이너리 처리가 끝났거나 앱 심사가 승인됐다는 뜻이 아닙니다.

Apple은 빌드 업로드 경로와 요구 역할을 별도로 안내합니다. Transporter 등 실제 전송 경로를 사용한다면, Apple의 빌드 업로드 절차에서 해당 경로의 요구 사항을 확인하세요. 인증이 통과해도 전송이 실패할 수 있고, 전송이 끝나도 App Store Connect에서 처리가 진행 중일 수 있습니다.

• [ ] 파이프라인에서 실행하는 fastlane action을 순서대로 적습니다.
• [ ] 각 action이 API Key 인증을 지원하는지 공식 문서에서 확인합니다.
• [ ] 키 유형과 연결된 역할이 작업에 필요한 접근 범위와 맞는지 확인합니다.
• [ ] .p8 개인 키를 저장소에 넣지 않고 제한된 비밀 정보 저장소에서 전달합니다.
• [ ] Apple ID가 필요한 작업만 분리하고, 앱 전용 암호를 범용 인증으로 취급하지 않습니다.
• [ ] 비공식 게시 작업에서 인증, 전송, 처리, TestFlight 상태를 각각 확인합니다.
• [ ] 작업자 변경 시 키 접근 권한과 교체 책임을 인계합니다.

원격 맥이나 CI를 현재 운영 환경으로 쓸지는 게시 작업을 실제로 검증한 뒤 결정하세요. 로컬 컴퓨터 한 대만 쓰면 해당 기기의 로그인 상태와 작업 가능 여부에 게시가 묶일 수 있고, CI만 사용하면 비밀 정보 전달과 실행 로그 관리 책임이 남습니다. 반복 게시를 위해 계속 접근할 수 있는 macOS 환경이 필요하다면 CALMVPS의 요금 안내를 검토하고, 사용 기간과 필요한 작업을 비교해 보세요. 게시 도구가 물리 기기나 로컬 전용 인터페이스에 의존하거나 장기간 고정된 환경이 필요한 경우에는 직접 보유한 맥이 더 적합할 수 있습니다. 임시 게시 검증이나 전용 환경이 필요한 경우에는 한국에서 이용하는 CALMVPS 안내를 확인한 뒤, 자신의 fastlane 흐름이 요구하는 권한과 접근 방식에 맞는지 판단하세요.