App Store Connect API Key를 원격 Mac에서 어떻게 설정할까요? 2026 튜토리얼

.p8 비공개 키는 한 번만 내려받을 수 있습니다

Apple은 App Store Connect API Key의 비공개 키를 한 번만 다운로드할 수 있다고 안내합니다. 따라서 먼저 fastlane 작업에 맞는 키를 고르고, .p8 파일을 원격 Mac의 통제된 위치에 안전하게 전달한 뒤, 저위험 작업으로 권한을 검증해야 합니다. 이 키는 App Store Connect 작업을 인증하지만 코드 서명 인증서와 Provisioning Profile을 대신하지 않습니다. Apple의 API Key 생성 및 관리 안내를 확인한 뒤 진행하세요.

이 글은 다음 개발자를 위한 안내입니다.

• 원격 Mac에서 fastlane 자동 업로드를 처음 설정하는 독립 iOS 개발자
• 로컬 Mac에서 원격 환경으로 출시 절차를 옮기는 소규모 팀
• 업로드는 되지만 비공개 키 노출과 권한 범위를 점검하려는 개발자

먼저 API 인증과 앱 서명을 분리합니다

App Store Connect API Key는 지원되는 API 또는 fastlane 작업에 대한 인증 수단입니다. 앱을 빌드하고 서명할 때 필요한 자격 증명과는 역할이 다릅니다. Apple의 개발 Provisioning Profile 안내에서도 프로파일 생성에 필요한 서명 관련 항목을 별도로 설명합니다.

팀 키와 개인 키는 적용 범위와 권한 조건이 다를 수 있습니다. 팀의 역할과 접근 권한을 먼저 확인하고, 실제로 실행할 action이 어떤 키를 지원하는지 fastlane의 App Store Connect API 안내에서 대조하세요. Apple의 역할별 권한 안내도 함께 확인해야 합니다.

주의: API 인증 오류와 서명 오류는 해결 경로가 다릅니다. API Key 인증은 성공했지만 빌드가 실패한다면, 인증서를 다시 만들기 전에 빌드 로그에서 서명 단계의 오류를 따로 찾으세요.

원격 Mac에 안전하게 전달할 준비를 합니다

원격 환경에서는 개인 개발용 Mac과 달리, 키 파일이 어느 작업에서 읽히고 어디에 남는지 점검해야 합니다. NUMACS의 특정 전송 방식이나 접근 제어 기능을 전제로 삼지 말고, 선택한 환경에서 실제로 제공하는 보안 기능을 확인하세요.

Apple의 안내에 따르면 비공개 키는 한 번만 다운로드할 수 있으므로, 다운로드 직후 안전한 보관 위치와 복구 절차를 확인해야 합니다. 이미 파일을 잃어버렸다면 같은 키를 다시 내려받을 수 있다고 가정하지 마세요. App Store Connect API Key 설명을 기준으로 새 키 발급 필요 여부를 확인하세요.

NUMACS 계정과 원격 환경의 이용 조건은 이용 안내에서 확인할 수 있습니다. 단, 이 안내만으로 특정 키 전송이나 저장 기능이 제공된다고 가정해서는 안 됩니다.

fastlane 설정에서 키 파일을 불러옵니다

fastlane 문서는 API Key를 구성하고 이를 지원되는 작업에 전달하는 방법을 설명합니다. 기본 확인 항목은 Key ID, 키 파일 경로, 그리고 해당하는 경우 Issuer ID입니다. fastlane API Key 설정 안내와 upload_to_testflight 매개변수 문서를 설치된 fastlane 버전 및 실제 사용하는 action과 대조하세요.

예시는 실제 인증값을 포함하지 않습니다. 비밀값 대신 환경 변수를 사용하고, 키 파일 경로는 실행 환경에서만 지정합니다.

api_key = app_store_connect_api_key(
  key_id: ENV.fetch("ASC_KEY_ID"),
  issuer_id: ENV["ASC_ISSUER_ID"],
  key_filepath: ENV.fetch("ASC_KEY_PATH")
)

upload_to_testflight(
  api_key: api_key
)

개인 키 설정에 Issuer ID가 필요한지는 키 종류와 fastlane의 현재 구현에 따라 확인해야 합니다. 환경 변수 이름은 예시일 뿐입니다. 실제 값과 파일 경로를 저장소에 기록하지 말고, 배포 작업이 키를 읽을 수 있는지 확인하세요.

이 설정에서 확인할 핵심 입력은 Key ID, 적용되는 경우의 Issuer ID, 비공개 키 파일 경로라는 세 항목입니다. 다만 이 세 항목을 넣었다고 모든 fastlane action이 API Key를 지원하는 것은 아닙니다. action별 지원 범위는 fastlane 공식 문서에서 다시 확인하세요.

낮은 위험도의 작업부터 검증합니다

업로드 명령을 바로 실행하기보다 원인을 분리해 확인합니다. 키 파일을 읽을 수 있는지 확인한 다음, 대상 작업에 필요한 권한이 있는지 점검하고, 마지막에 실제 빌드 업로드를 수행합니다.

• [ ] 원격 Mac의 fastlane 버전과 실행하는 action을 확인합니다.
• [ ] 해당 action이 App Store Connect API Key 인증을 지원하는지 공식 문서에서 확인합니다.
• [ ] 비공개 키 파일이 예상 경로에 있고 작업 계정에서 읽히는지 확인합니다.
• [ ] Key ID와 필요한 Issuer ID가 선택한 키와 일치하는지 확인합니다.
• [ ] 키 내용을 출력하지 않는 저위험 작업으로 인증을 검증합니다.
• [ ] 인증 검증 후 빌드 서명, 업로드, App Store Connect의 처리 상태를 각각 확인합니다.

오류가 나면 다음처럼 분류합니다. 인증 오류는 키의 종류, 역할, 식별값, action 지원 여부를 확인합니다. 파일 읽기 오류는 경로와 접근 권한을 확인합니다. 빌드 서명 오류는 인증서와 Provisioning Profile을 점검합니다. 업로드 명령이 성공으로 끝났더라도 App Store Connect에서 실제 빌드가 도착했는지 확인해야 합니다.

참고: fastlane의 TestFlight 업로드 action은 API Key 관련 매개변수를 지원하지만, 설치된 버전과 사용 중인 구성에 따라 세부 동작이 달라질 수 있습니다. 매개변수는 upload_to_testflight 문서에서 확인하세요.

키 교체와 출시 기록을 운영 절차에 포함합니다

담당자가 바뀌거나 키 파일을 잃어버렸거나 노출이 의심되면 해당 키를 계속 사용하지 말고 Apple의 절차에 따라 폐기와 재설정을 검토합니다. Apple은 키 폐기에 관한 안내를 제공하며, 폐기한 키를 복구할 수 있다고 전제해서는 안 됩니다. 최신 절차는 API Key 폐기 안내에서 확인하세요.

출시 기록에는 사용한 fastlane 버전, 실행한 action, 키 식별 정보, 인증 결과, 빌드 서명 결과, App Store Connect에서 확인한 업로드 결과를 남깁니다. 비공개 키 값이나 파일 내용은 기록하지 않습니다. 새 키로 전환한 뒤에는 이전 키가 더 이상 배포 작업에서 쓰이지 않는지도 확인하세요.

자주 묻는 질문

원격 Mac에서 fastlane이 API Key를 읽게 하려면 어떻게 설정하나요?

Key ID와 해당하는 경우 Issuer ID, 비공개 키 파일 경로를 fastlane 설정에 연결합니다. 저장소에 비밀값을 넣지 말고, 원격 실행 환경에서 안전하게 전달하세요. 사용 중인 action이 API Key 인증을 지원하는지 문서로 확인한 뒤 낮은 위험도의 작업으로 검증합니다.

.p8 파일은 원격 Mac의 어느 위치에 두어야 하나요?

저장소나 앱 코드가 아닌, 배포 작업에 필요한 계정만 읽을 수 있는 통제된 위치를 사용합니다. 파일 경로뿐 아니라 작업 종료 후 사본이 남는지와 로그에 비밀값이 노출되는지도 점검하세요. Apple은 비공개 키를 한 번만 내려받을 수 있다고 안내하므로 다운로드 직후 안전하게 보관해야 합니다.

TestFlight 업로드 전에 API Key 권한을 어떻게 확인하나요?

먼저 업로드 action이 API Key를 지원하는지 확인합니다. 다음으로 키의 역할, 식별값, 파일 접근 상태를 점검하고 목표 작업에 필요한 권한을 낮은 위험도의 요청으로 검증합니다. 인증 확인과 빌드 서명은 별도 단계입니다. 마지막에는 App Store Connect에서 빌드가 도착했는지도 확인하세요.

API Key로 iOS 앱 서명까지 처리할 수 있나요?

아니요. API Key는 지원되는 App Store Connect 작업의 인증에 사용하며, 앱 서명에 필요한 인증서와 Provisioning Profile을 대신하지 않습니다. API 인증에 성공해도 서명 설정이 잘못되면 빌드는 실패할 수 있습니다. 인증, 서명, 업로드 결과를 서로 다른 단계로 나누어 확인하세요.

API Key가 목표 작업에 맞고 fastlane 인증까지 검증됐다면, 남은 점검은 Mac 빌드 환경과 업로드 흐름이 출시 절차에 맞는지 확인하는 일입니다. 로컬 Mac에서 계속 작업하면 노트북의 실행 상태와 디스크 공간에 의존하고, 키 파일을 개발 기기와 배포 환경에 나누어 보관해야 할 수 있습니다. 반대로 원격 Mac은 별도 구매 없이 macOS 환경을 사용할 수 있는 선택지지만, 잦은 물리적 접근이 필요하거나 같은 Mac을 장기간 고정 부하로 운용한다면 구매가 더 적합할 수 있습니다. 원격 환경을 검토하는 경우 NUMACS의 이용 옵션과 시작 안내를 살펴보고, 사용 중인 fastlane 작업과 보안 요구에 맞는지 먼저 판단하세요.

자주 묻는 질문