2026년 전용 원격 Mac CI: App Store Connect API(.p8)와 Fastlane app_store_connect_api_key — SSH 헤드리스 환경의 키 보관·회전·파이프라인 주입 의사결정 매트릭스 + FAQ

1. TL;DR — 문자열 세 개와 파일 하나

• .p8 파일: API 키를 만들 때 App Store Connect에서 한 번만 내려받는 타원곡선 개인 키입니다. 비밀번호처럼 취급하세요. Apple은 다시 보여 주지 않습니다.
• Key ID: 해당 키의 짧은 식별자(ASC에 표시).
• Issuer ID: 동일 계정 맥락에서 만든 키들이 공유하는 팀 단위 UUID.
• Fastlane: app_store_connect_api_key(또는 환경 변수 기반 동등 설정)로 넘겨 Match, pilot, deliver 등 API 기반 액션이 Apple ID 세션이 아니라 토큰 인증을 쓰게 합니다.
• 헤드리스 SSH 경험칙: “누가 ~/Downloads에 .p8을 SCP해 둠”보다 CI 네이티브 시크릿(암호화 변수, 시크릿 매니저, 러너 키체인 등)을 우선하세요.

2. ASC API 키의 정체

.p8는 App Store Connect API 호출을 허용하는 짧은 수명 JWT에 서명하는 데 쓰이는 개인 키입니다. 배포 인증서나 App Store 프로비저닝 프로파일과 같지 않습니다. 둘을 혼동하면 “ASC API를 돌렸는데” 실제로는 코드 서명이나 노타라이제이션 자격을 고쳐야 하는 상황을 놓칩니다.

권한은 키 생성 시 ASC에서 정합니다(Developer, App Manager, Admin 등). Fastlane에 필요한 최소한만 주는 최소 권한을 권장합니다(예: 업로드 vs 사용자 관리).

3. Fastlane 연결(app_store_connect_api_key)

Fastfile에서는 보통 app_store_connect_api_key를 한 번 호출해 반환 객체를 이후 액션에 재사용합니다. 개념적으로는 다음을 넘깁니다.

• key_id — ASC 값
• issuer_id — 팀 Issuer UUID
• key_filepath — 디스크의 .p8 경로, 또는
• key_content — PEM 본문 인라인(환경 변수에서 읽는 경우가 많음)

시크릿에서 key_content를 쓰면 파일 경로 규약을 저장소에 박을 필요는 줄지만, 파이프라인이 변수를 디버그 로그에 찍지 않도록 해야 합니다. PEM을 담은 변수는 CI의 “시크릿 마스킹” 옵션을 켜 두세요.

4. 의사결정 매트릭스: 헤드리스 Mac에서 .p8을 어디에 둘까

행은 저장 패턴, 열은 SSH로 주로 접속하는 전용 원격 Mac에서의 트레이드오프입니다.

5. 파이프라인 주입: 시크릿이 Fastlane까지 가는 방법

“오케스트레이터”와 “Mac 워커” 사이에는 하나의 명확한 계약을 정하세요.

• 환경 변수 — 예: Issuer는 APP_STORE_CONNECT_API_KEY_ISSUER_ID, Key ID는 APP_STORE_CONNECT_API_KEY_KEY_ID, PEM 본문은 APP_STORE_CONNECT_API_KEY_KEY 등 Fastlane env 규약에 맞춤. 로그에서 마스킹.
• 일회성 파일 — 잡이 PEM을 temp에 쓰고 chmod 600, key_filepath로 넘긴 뒤 after_all·trap에서 삭제.
• SSH 원격 명령 — 제어 평면이 전역 셸 프로필이 아니라 ssh 세션에만 변수를 export해 실수로 남지 않게 함.

피할 것: PEM을 저장소, Terraform state, Docker 이미지에 박기 — “비공개” 레지스트리라도 마찬가지입니다.

6. SSH 헤드리스만의 포인트(로그·세션·사용자)

• 러너 정체성: CI를 전용 macOS 사용자로 돌리고 홈·파일 권한을 통제하세요. 다른 서명 시크릿과 동일한 규율입니다.
• 로깅: Ruby/Fastlane 스택 트레이스가 경로나 env 이름을 흘릴 수 있습니다. 운영 파이프라인에서는 verbose 대신 비공개 디버그 세션에서만 켜세요.
• 병렬 잡: 한 사용자·한 디스크 .p8 경로를 공유하면 읽기 경합은 거의 없지만 파급 범위는 공유됩니다. 잡별 temp 또는 사용자 분리와 DerivedData·키체인 분리를 함께 고려하세요. 서명 레이어 경합은 본 블로그의 병렬 키체인·codesign 글을 참고하면 됩니다.

7. 업로드를 망가뜨리지 않는 회전

1. ASC에서 동일하거나 좁힌 역할로 새 API 키 생성.
2. 이전 키를 폐기하기 전에 새 Issuer/Key ID·PEM을 CI 시크릿에 배포(겹침 구간).
3. 전용 Mac에서 스모크 잡 실행(fastlane spaceship ping 또는 드라이런 레인).
4. 트래픽이 새 키로만 가는 게 확인되면 ASC에서 구 키 폐기.
5. 문서화: 날짜와 어떤 파이프라인이 어떤 Key ID를 썼는지 — 감사에서 묻습니다.

8. FAQ

Q1: 노타라이제이션과 App Store 업로드에 같은 .p8을 쓸 수 있나요?

App Store Connect API 키는 ASC API와 이를 쓰는 다수 Fastlane 액션에 쓰입니다. notarytool로 하는 노타라이제이션도 키체인 프로필이나 API 키 플래그를 쓸 때 App Store Connect API 키 매개변수를 맞추는 경우가 많습니다. 사용 중인 Xcode 버전의 Apple CLI 문서를 기준으로 하세요. 중요한 것은 ASC API 키와 Developer ID 서명 인증서를 섞지 않는 것입니다.

Q2: 변경 직후 “Invalid issuer”나 JWT 오류?

대부분 Issuer ID·Key ID 오타, 팀 불일치, PEM 손상(CI UI에 붙여 넣을 때 줄바꿈 제거 등)입니다. PEM을 그대로 다시 복사하거나 끝까지 base64로 전달하세요.

Q3: .p8을 Match 인증서와 같은 폴더에 두어야 하나요?

필수는 아닙니다. Match는 코드 서명 신원을, ASC API 키는 ASC 인증을 담당합니다. 파급 범위를 줄이려면 시크릿 네임스페이스를 나누는 편이 낫습니다.

Q4: PEM을 macOS 키체인에 두는 편이 더 나은가요?

정책상 그럴 수 있습니다. 다만 헤드리스 자동화는 그 키체인에 예측 가능하게 접근해야 합니다. 많은 팀이 SSH 너머 키체인 ACL 디버깅보다 CI 시크릿 + 일회 파일 또는 env가 이해하기 쉽다고 봅니다.

Q5: 얼마나 자주 회전해야 하나요?

세션 쿠키와 달리 .p8은 기본적으로 짧은 주기로 “만료”되지 않습니다. 인력·프로세스 변화, 유출 의심, 규정 캘린더에 맞춰 회전하고 런북에 기록하세요.

안정적인 Apple 하드웨어에서 ASC 자동화를

API 키와 Fastlane만으로 끝이 아닙니다. Xcode, Ruby·Bundler, 러너 스택이 긴 파이프라인 내내 온라인인 믿을 만한 macOS 호스트가 필요합니다. Apple 실리콘 Mac mini급은 Swift 빌드에 유리한 단일 스레드·통합 메모리 동작을 제공하고, macOS는 Gatekeeper·SIP·전원 관리 덕분에 임시 PC보다 무인 잡이 덜 깨집니다. 대기 전력도 M 시리즈 Mac mini는 낮아 전용 CI 노드를 상시 켜 두기 부담이 적습니다. .p8 처리와 Fastlane 레인을 표준화한다면, 그걸 Mac mini M4급 원격 호스트에 올리면 환경 편차 — “Apple API가 고장 난 것처럼” 보이는 종류 — 를 줄일 수 있습니다.

이 글의 SSH 우선 워크플로에 맞는 전용 원격 Mac을 찾는다면 SSHMac 홈에서 하드웨어를 고른 뒤 시크릿 주입 방식을 고정하는 것을 권장합니다.