빌드 업로드는 되지만 팀원이 바뀔 때마다 같은 비밀 키를 넘기고 있다면, 권한과 철회 범위를 다시 나눠야 합니다. 지정한 앱만 다루는 저빈도 자동화라면 제한된 사용자에 연결된 개인 API 키를 먼저 선택하고, 프로비저닝 관련 API나 개인 키가 지원하지 않는 기능이 필요할 때만 최소 역할의 독립 팀 API 키로 전환하면 됩니다.

이 글을 읽어야 하는 사람

혼자 빌드와 TestFlight 업로드를 처리하면서 Apple 계정 로그인 정보를 자동화 도구에 넣고 싶지 않은 개발자에게 적합합니다. 여러 앱의 출시 권한을 나누려는 소규모 팀을 이끄는 담당자와, 상시 원격 맥에서 fastlane, Transporter 또는 자체 배포 스크립트를 운영하는 담당자도 대상입니다.

먼저 나눠야 할 네 가지 권한 경계

App Store Connect API 키는 코드 서명에 필요한 모든 비밀 정보를 대신하지 않습니다. 다음 네 가지를 서로 다른 출입구로 관리해야 합니다.

  • App Store Connect 권한: 앱 정보, 빌드, TestFlight, 판매 및 분석 자료에 접근하는 권한입니다.
  • 인증서·식별자·프로파일 권한: Certificates, Identifiers & Profiles에서 서명 자료를 만들거나 관리하는 권한입니다.
  • 원격 맥 로그인 권한: VNC, SSH 또는 웹 콘솔로 호스트에 들어가는 계정 권한입니다.
  • 코드 서명 개인 키: 인증서와 함께 빌드 서명을 완성하는 별도 비밀 자료입니다.
Apple은 API 키를 사용자 권한 또는 팀에서 부여한 역할과 연결합니다. 키를 만들 수 있는 사람, 선택할 수 있는 역할, 앱 접근 범위는 계정 설정과 역할에 따라 달라지므로 [Apple의 API 키 생성 안내](https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api)와 [역할별 권한 문서](https://developer.apple.com/help/app-store-connect/reference/account-management/role-permissions)를 함께 확인해야 합니다.

특히 팀 API 키는 역할을 선택할 수 있지만 단일 앱만 지정하는 방식의 격리를 제공하지 않습니다. 여러 프로젝트마다 팀 키를 새로 만들어도 각 키가 특정 앱 하나에만 묶이는 것은 아닙니다. 앱 단위 격리가 필요하다면 제한된 앱 접근이 가능한 별도 사용자 계정과 개인 키를 먼저 검토해야 합니다.

개인 개발자는 제한된 사용자와 개인 키로 시작합니다

개인 키가 맞는 작업 범위

한 명이 한정된 앱의 빌드 업로드, TestFlight 관리 또는 메타데이터 자동화를 수행한다면 Individual API Key가 먼저 검토할 선택입니다. 개인 키는 연결된 사용자의 권한과 앱 접근 범위를 따르므로, 사용자가 볼 수 없는 앱을 키만으로 새로 열 수 없습니다.

개인 키의 장점은 책임 소재가 분명하다는 점입니다. 개발자 한 명의 사용자 계정에 연결되므로 팀 전체가 공유하는 장기 비밀 키를 만들 필요가 없습니다. Apple은 개인 키의 생성과 관리 조건을 별도로 설명하며, 사용자마다 유효한 개인 키를 1개만 유지할 수 있는 제약도 안내합니다. 도구를 바꾸기 전에 기존 키를 바로 폐기하면 이전 자동화가 함께 멈출 수 있으므로 개인 키 생성 조건을 먼저 확인해야 합니다.

다음 조건이면 개인 키에서 멈춰도 됩니다.

  • 자동화 대상이 특정 사용자가 접근할 수 있는 앱으로 제한됩니다.
  • 빌드 업로드와 TestFlight 배포가 주된 작업입니다.
  • 인증서나 프로파일을 API로 새로 만들 필요가 없습니다.
  • 키의 소유자가 바뀌면 새 사용자에게 작업을 넘길 수 있습니다.

개인 API 키가 부족해지는 지점

개인 API 키가 iOS 인증서와 프로비저닝 프로파일을 모두 관리한다고 가정하면 안 됩니다. 필요한 API 경로가 개인 키에서 지원되는지, 그리고 연결된 사용자의 Certificates, Identifiers & Profiles 권한이 충분한지 별도로 확인해야 합니다.

프로비저닝 관련 엔드포인트나 개인 키가 지원하지 않는 자동화 능력이 필요하면 팀 키로 전환할 조건이 생깁니다. 단, 이것은 무인 실행이므로 관리자 권한을 준다는 뜻이 아닙니다. 실제 호출 목록을 적고, 그 호출에 필요한 가장 낮은 역할만 부여해야 합니다.

소규모 팀은 역할과 앱 격리를 따로 설계합니다

Team API Key와 Individual API Key의 차이

Team API Key는 팀 단위의 자동화 작업에 적합할 수 있습니다. 다만 팀에서 선택한 역할의 범위와 앱 접근 방식이 개인 키와 다릅니다.

  • Team API Key: 팀의 자동화 주체로 사용할 수 있으며, 선택한 팀 역할의 권한을 따릅니다. 단일 앱만 허용하는 격리 수단으로 사용할 수 없습니다.
  • Individual API Key: 특정 사용자의 권한과 앱 접근 범위를 따릅니다. 사용자별 책임과 앱 범위를 나누는 데 유리합니다.
  • 공유 고권한 키: 담당자 교체와 사고 대응이 어렵습니다. 팀원이 많아질수록 누가 사용했는지 추적하기도 힘듭니다.
역할은 출시 책임자, 일반 개발자, 자동화 전용 계정으로 나눠 검토합니다. Admin을 기본값으로 두지 말고, 빌드 업로드와 TestFlight 배포에 실제로 필요한 작업부터 확인합니다. Apple의 [역할 권한 기준](https://developer.apple.com/help/app-store-connect/reference/account-management/role-permissions)을 기준으로 사람이 사용하는 권한과 기계가 사용하는 권한을 분리해야 합니다.

팀 키를 여러 개 만들면 앱이 분리될까요?

분리되지 않습니다. 팀 키를 앱별로 여러 개 발급해도 팀 키 자체가 단일 앱 범위로 제한되는 것은 아닙니다. 앱 사이의 사고 범위를 줄여야 한다면 다음 순서가 더 안전합니다.

  1. 앱별 담당자를 별도 사용자로 초대합니다.
  2. 해당 사용자에게 필요한 앱 접근만 부여합니다.
  3. 그 사용자에게 개인 API 키를 연결합니다.
  4. 개인 키로 부족한 호출만 별도 팀 키로 옮깁니다.
  5. 팀 키를 사용한다면 전용 계정, 최소 역할, 짧은 사용 범위를 기록합니다.
이 구조는 팀 키를 완전히 금지하는 방식이 아닙니다. 다만 팀 키가 앱 단위 방화벽이 아니라는 사실을 전제로 선택하게 합니다.

외부 협력자는 사용자 계정과 호스트 계정을 분리합니다

외부 개발자가 지정된 앱의 TestFlight 업로드만 해야 한다면 팀 전체가 공유하는 장기 팀 키를 전달하지 않는 편이 낫습니다. 앱 범위를 제한할 수 있는 별도 사용자 계정을 만들고, 필요한 역할만 부여한 뒤 개인 키를 연결하는 방식을 먼저 검토합니다.

원격 맥을 사용해야 하는 협력자라면 다음 권한을 따로 회수해야 합니다.

  • App Store Connect 사용자 초대 및 역할
  • API 키와 개인 키 파일
  • 원격 맥의 SSH, VNC 또는 웹 콘솔 계정
  • 저장소 접근 토큰과 코드 서명 자료
프로젝트가 끝났을 때 사용자 제거만으로 충분하지 않습니다. API 키 철회, 호스트 로그인 계정 삭제, 저장된 서명 자료와 환경 변수 제거를 각각 수행해야 합니다. Apple은 API 키를 철회하면 해당 키를 사용한 API 요청이 더 이상 인증되지 않는다고 설명하므로 [공식 철회 절차](https://developer.apple.com/documentation/appstoreconnectapi/revoking-api-keys)를 기준으로 확인합니다.

지속적 통합 담당자는 호출 능력부터 고릅니다

fastlane 자동 업로드에 팀 키와 개인 키 중 무엇을 쓸지는 실행 위치가 아니라 실제 호출 능력으로 결정합니다. 단순한 빌드 업로드라면 개인 키를 우선 검토하고, 프로비저닝 자료를 무인으로 관리하거나 개인 키에서 지원하지 않는 호출이 있으면 독립 팀 키를 검토합니다.

Transporter 또는 자체 API 스크립트를 사용하는 경우에도 같은 원칙을 적용합니다. JWT는 Apple의 토큰 생성 문서에 따라 만들되, 다음 값은 저장 위치를 나눕니다.

  • Issuer ID: 환경 설정에 둘 수 있지만 공개 로그에는 남기지 않습니다.
  • Key ID: 키 식별에 사용하며 로그에 그대로 출력하지 않는 편이 좋습니다.
  • 개인 키 파일: 저장소, 빌드 결과물, 공개 로그에 넣지 않습니다.
  • JWT: 만료 시각과 대상 권한을 확인하고 명령어 출력에 전체 값을 표시하지 않습니다.
원격 맥에서 저장할 때는 저장소 파일 대신 비밀 저장소나 실행 시 주입하는 환경 변수를 사용합니다. [MACGPU의 원격 맥 환경](https://macgpu.com/ko/index.html)을 검토하더라도, 호스트 로그인 권한과 App Store Connect 비밀 키를 같은 계정에 묶지 않는 설계가 우선입니다.

역할별 선택을 체크리스트로 확정합니다

아래 항목을 위에서부터 확인하십시오. 왼쪽 조건을 만족하면 개인 API 키를 선택하고, 오른쪽 조건이면 최소 역할 팀 키를 검토합니다.

  • [ ] 자동화 대상이 지정된 앱 하나 또는 제한된 앱 범위입니까?
→ 그렇다면 제한된 사용자와 개인 API 키를 우선 선택합니다. 여러 앱을 한 번에 다뤄야 한다면 팀 키의 넓은 앱 범위를 별도로 평가합니다.
  • [ ] 작업이 빌드 업로드, TestFlight 배포, 기본 메타데이터 자동화에 그칩니까?
→ 그렇다면 개인 키를 먼저 시험합니다. 개인 키가 해당 호출을 지원하는지 실제 테스트 앱으로 확인합니다.
  • [ ] 프로비저닝 관련 API나 개인 키가 지원하지 않는 기능이 필요합니까?
→ 그렇다면 독립 팀 API 키를 검토합니다. 필요한 호출에 맞는 가장 낮은 역할을 선택하고 Admin을 기본값으로 사용하지 않습니다.
  • [ ] 외부 협력자가 특정 앱만 업로드합니까?
→ 그렇다면 별도 사용자 계정, 제한된 앱 접근, 개인 키를 우선 적용합니다. 팀 전체가 공유하는 장기 키는 전달하지 않습니다.
  • [ ] 원격 맥에서 무인 실행합니까?
→ 그렇다고 최고 역할을 부여하지 않습니다. API 권한, SSH 또는 VNC 로그인, 코드 서명 자료를 별도로 관리합니다.
  • [ ] 담당자 교체나 프로젝트 종료가 예정되어 있습니까?
→ 사용자 제거, API 키 철회, 호스트 계정 삭제, 환경 변수와 서명 자료 정리를 각각 기록합니다.

계정 관리자는 발급과 철회를 5단계로 검증합니다

1. 실제 작업 목록을 고정합니다

빌드 아카이브, 업로드, TestFlight 배포, 메타데이터 변경, 프로비저닝 자료 관리 중 무엇이 필요한지 적습니다. “배포 자동화”처럼 넓은 표현만 남기면 불필요한 역할을 고르게 됩니다.

2. 사용자와 팀 키 후보를 분리합니다

앱 범위를 좁혀야 하는지, 개인 키가 필요한 API를 지원하는지 확인합니다. Apple은 키 생성 조건과 권한을 계정 역할에 따라 구분하므로 생성 안내를 계정 관리자와 함께 대조합니다.

3. 비밀 값을 안전하게 주입합니다

키 파일을 저장소나 아카이브에 넣지 않습니다. 원격 맥에서는 실행 시 주입하고, 로그에는 전체 JWT와 개인 키가 출력되지 않도록 합니다. 자동화 계정의 SSH 권한도 API 키와 별도로 설정합니다.

4. 통제된 실제 빌드를 수행합니다

테스트 앱으로 Archive, 인증, 업로드, TestFlight에서의 빌드 표시를 각각 확인합니다. Apple의 빌드 업로드 절차와 TestFlight 동작 안내를 기준으로, 명령어가 성공을 반환한 뒤 애플 처리 결과까지 확인해야 합니다.

5. 이전 키를 철회하고 재사용을 막습니다

새 키가 실제 배포를 완료한 뒤 이전 키를 철회합니다. 자동화 로그와 환경 변수에서 이전 Key ID를 제거하고, 철회 뒤 같은 명령이 실패하는지도 확인합니다. 기록에는 담당자, 사용 목적, 교체 조건만 남기고 개인 키 본문은 복사하지 않습니다.

**경험** 팀 키의 이름이나 역할을 바꿔야 하는 상황에서는 기존 키를 수정할 수 있다고 가정하지 마십시오. 현재 설정으로 목적을 달성할 수 없다면 철회 후 새 키를 만들고, 새 키의 실제 동작을 검증한 뒤 교체하는 편이 추적하기 쉽습니다.

현재 방식과 원격 맥 운영을 비교해 결정합니다

이미 보유한 개인 맥에서 모든 작업을 처리하면 하드웨어를 추가하지 않아도 되지만, 디스크 공간과 빌드 중 자원 점유가 다른 작업을 막을 수 있습니다. 개인 맥이 꺼져 있거나 네트워크가 바뀌면 야간 배포와 협력자 접근도 중단됩니다. 별도 빌드 장비를 직접 구매하면 초기 비용과 운영 책임이 생기고, 서명 자료 백업과 운영 체제 업데이트도 직접 관리해야 합니다.

반대로 팀 키를 원격 맥에 오래 두는 방식은 키 범위가 넓어질 수 있고, 호스트 로그인 권한과 API 권한이 함께 노출되면 사고 범위가 커집니다. 그래서 원격 Mac에서 지속 발행을 운영하려면 독립 관리자 권한, 안전한 비밀 값 주입, 지속 접속, 환경 복구 조건을 먼저 확인해야 합니다. 이 조건이 맞고 발행 주기가 일정하지 않다면 MACGPU의 맥 임대 선택지를 검토하는 편이 전용 장비를 계속 켜 두는 것보다 운영 부담이 낮을 수 있습니다.

단, 물리 장치 연결이 필요하거나 장기간 높은 부하의 빌드를 매일 반복한다면 직접 보유한 맥이 더 적합할 수 있습니다. 반대로 단기 출시, TestFlight 반복 확인, 협력자용 분리 환경처럼 사용 기간이 유동적이면 원격 맥 임대가 더 현실적인 선택입니다. 핵심은 팀 키를 임대한 호스트에 올리는 것이 아니라, 어떤 키를 쓰더라도 앱 범위와 호스트 권한을 따로 통제하는 데 있습니다.