2026 Mac 클라우드 CI의 Apple 공증(Notarization): notarytool, 흔한 거절, 헤드리스 SSH 대 짧은 데스크톱 세션 판단표
xcodebuild archive는 Mac 클라우드에서 안정적이어도 공증에서 막히는 경우가 많다. API Key 오설정, 거절 로그 해석, 로컬 GUI에서는 통과하지만 CI만 실패하는 패턴을 Runbook으로 쪼갠다. 실패 유형 표로 먼저 분류하고, 순수 SSH로 충분한지 짧은 VNC가 필요한지 표로 결정한 뒤, notarytool 제출·폴링·stapler·로그 보존을 다섯 단계로 정리한다. 디스크 여유와 공증 동시 실행도 수치 가이드를 덧붙인다.
1. 서명, 공증, App Store 업로드를 분리하라
셀프호스팅 Mac은 Linux VPS처럼 SSH로 관리하지만 코드 서명, Apple 공증, TestFlight 업로드는 서로 다른 자격 증명과 실패 의미를 가진다. 서명은 codesign과 프로비저닝, Hardened Runtime이며 로그는 xcodebuild에 쏟아진다. 공증은 zip·dmg·pkg를 보내 원격 스캔을 기다리며 거절은 notarytool JSON이나 log에 잡힌다. 업로드는 별도 App Store Connect API Key와 엔드포인트를 쓰므로 Secrets를 한 바구니에 넣으면 층별 트리아지가 무너진다. 야간 파이프라인을 살리려면 세 계층을 잡 단위로 나누는 것이 첫 단계다.
- 서명: Archive·export 단계에서 실패,
xcodebuild로그가 중심. - 공증: 제출물을 보내고 스캔 대기, CLI 출력이 중심.
- 업로드: Transporter·Fastlane 등, 권한 집합이 공증과 다름.
이 분리는 “로컬에선 되는데 CI만 깨진다” 루프를 줄이는 데 직접적으로 기여한다.
2. CI 공증 실패 표
포스트모템에서 entitlements를 먼저 볼지 API Key·출구를 의심할지 빠르게 가른다.
| 증상 | 가능 원인 | 첫 조치 |
|---|---|---|
| 즉시 인증 실패 | Issuer·Key ID 오류, 만료, 시크릿 줄바꿈 손실 | .p8 경로, CI 멀티라인 주입 |
| 오래 In Progress | 큐, 대용량 패킷 | submission id 보존, notarytool log, 백오프 연장 |
| Hardened Runtime 거절 | 미서명 헬퍼, 위험 entitlement | codesign --verify --deep |
| GUI 있는 로컬만 성공 | 키체인·대화형 의존 | §3 표로 VNC 또는 수동 게이트 |
3. 헤드리스 SSH와 짧은 데스크톱
기본값은 API Key와 비대화형 notarytool이다. 감사에는 빌드 디렉터리에 JSON·텍스트를 남기는 편이 낫다. 7×24·다브랜치에는 헤드리스가 유리하고 예외만 짧은 데스크톱 큐로 분리해 무거운 xcodebuild와 경쟁하지 않게 한다. launchd로 PATH와 Xcode 버전을 고정하고 CI에서도 명시 버전을 선택해 조용한 업그레이드로 행동이 바뀌지 않게 한다.
| 관점 | 헤드리스 | 짧은 VNC |
|---|---|---|
| 자격 | API Key만 | 키체인·GUI 전용 도구 |
| 감사 | 아티팩트 동봉 쉬움 | 녹화·이중 확인 부담 |
| 운영 | 반복에 강함 | 저빈도 예외에 적합 |
4. 다섯 단계: submit → poll → staple → 보관 → 롤백
- 툴체인 고정: 이미지에서
xcodebuild -version기록, CI에서 명시 선택. - 제출물 준비: sha256, 경로 권한, 큰 zip은 임시 공간 선확보.
- submit:
notarytool submitstdout·JSON을artifacts/notary/submit.log에. - poll:
notarytool info등으로 지수 백오프. 실패 시notarytool log를 스토어에 첨부. - staple: 성공 후
xcrun stapler staple. 실패 시 릴리스 중단, 마지막 양호 staple 버전 유지.
5. 디스크·타임아웃·동시성
Linux 습관으로는 임시 디렉터리와 키체인 차이를 과소평가하기 쉬운데 공증은 로컬 전개·재압축으로 IO가 튄다. Archive 이후에도 시스템 볼륨에 약 25GB급 피크 여유를 보고 10GB 미만이면 새 공증 잡을 거절하고 DerivedData·오래된 ipa부터 정리한다. 단일 submission 폴링 상한은 패킷에 따라 45~90분로 알람을 건다. 한 호스트에서 notarytool을 병렬로 돌리면 CPU·디스크가 싸우므로 공증 동시성은 1~2로 제한하고 무거운 xcodebuild와 시간대를 어긋낸다. notary JSON·텍스트는 90일 이상 보관하고 업로드 로그와 버킷을 분리한다. 공증 전용 API Key를 메타데이터 변경 권한과 분리해 90일 로테이션을 권한다.
- 디스크: 25GB 버퍼 목표, 10GB 이하 게이트.
- 폴링: 제출과 완료를 별 KPI로.
- 동시성: 공증 1~2 레인.
6. FAQ
TestFlight보다 공증이 먼저인가? 보통 서명과 필요한 staple을 먼저 하고 export 형태에 맞춰 Runbook에 순서를 박는다. Gatekeeper와 ASC 상태 불일치를 막는다.
네트워크 불안정: HTTPS_PROXY·NO_PROXY를 공증 도메인과 업로드 도메인에 나눠 점검한다.
VNC를 없앨 수 있나? 대부분의 최신 파이프라인에서 가능하다. 키체인 의존은 비밀 분할과 드문 수동 게이트가 현실적이다.
노트북만 믿으면 절전·정책에 깨지기 쉽고 분당 과금 호스트는 대용량 공증·큐 대기에서 비용과 재현성이 떨어진다. Apple 툴체인을 예측 가능하게 유지하고 API Key를 감사하기 쉬운 팀은 전용 Mac 클라우드에 서명·공증·업로드를 올리는 편이 확장에 유리하다. VPSMAC TestFlight 글과 함께 잡 경계와 시크릿을 한 번에 맞추라. 완전한 Linux 대체는 아니지만 iOS·macOS 배포에는 Apple 하드웨어가 필수이며 장기적으로 임대 Mac 노드가 자체 하드웨어 유지보다 운용 부담이 낮은 경우가 많다.