플랫폼 팀은 Archive는 이미 녹색으로 만들었지만 공증(Notarization) 또는 stapler 때문에 밤을 새우기도 합니다. 키체인 프롬프트, 폴링 타임아웃, 동일 원격 Mac에서 여러 Job이 임시 경로를 두고 다투는 문제입니다. macOS를 전용 빌드 플레인으로 다루는 엔지니어를 위해, 무인 공증 뒤에 숨은 가정을 드러내는 체크 항목 일곱 가지, staple이 필수인지 알려 주는 배포 채널 매트릭스, API 키·notarytool submit/store·로그 보존·재시도·동시성 경계를 담은 여섯 단계 Runbook을 정리했습니다. 역할 분담을 위해 Fastlane과 CI, 재현 가능 빌드와 키체인 가이드와 함께 읽을 수 있습니다.
Apple 문서상 공증은 직선적이지만 장기 CI 사용자와 공유 NVMe 위에서는 실패가 간헐적으로 보이고 재현이 어렵고 로그도 갈라집니다. 아래 일곱 항목은「아마 자동화할 수 있을 것」에서「변경 티켓에 적을 수 있다」로 위험을 옮깁니다.
공증을 Archive의 부속으로 취급: notarytool에 대한 종료 코드 처리와 산출물 보존을 분리하지 않으면 사건은 마지막으로 파이프라인을 건드린 사람에게 되돌아갑니다. 릴리스 감사 모델과 필드를 맞춥니다.
개인 Apple ID와 CI API 키 혼용: 세션 기반 자격 증명은 무인 환경에서 깨지기 쉽습니다. 2026년에는 App Store Connect API 키를 기본으로 하고 헤드리스 Fastlane 릴리스와 동일한 비밀 계약을 맞춥니다.
stapler 의미 무시: 모든 파이프라인에 staple을 넣으면 벽시계 시간과 실패 면이 늘어납니다. 다음 절 매트릭스에 따라 직접 다운로드, 엔터프라이즈 포털, TestFlight 전용 흐름으로 분기합니다.
여러 Job이 기본 임시 공간 공유: /var/folders나 임시 zip 작업 공간 충돌로 업로드가 손상되거나 해시가 바뀔 수 있습니다. DerivedData와 같이 파이프라인별 버킷을 씁니다.
Apple 큐에 대한 선형 재시도: 서비스가 바쁠 때 순진한 루프는 동일 제출을 계속 두드립니다. 지수 백오프, 벽시계 예산, 티켓 시스템에 submission id 기록을 사용합니다.
키체인과 TCC를 데스크톱 사용자처럼 구성: 무인 빌드에는 전용 로그인 세션이나 명시적 CI 키체인 파티션이 필요합니다. 재현 가능 빌드의 키체인 계약과 함께 검토합니다.
공증 실패 샘플 라이브러리 부재: 팀이 녹색일 때만 로그를 읽으면 Invalid나 Hardened Runtime 퇴행에 버전 삼중항과 스크린샷이 없습니다. 지식 베이스에 캡처 템플릿을 표준화합니다.
공통 원인은 원격 Mac을「Xcode가 돌아가는 Linux」로 보고 공증 상태기와 키체인 경계를 가진 전용 노드로 보지 않는 것입니다. 엔터프라이즈 빌드 풀과 짝을 이루세요. 많은 앱이 플릿을 공유할 때 공증 동시 실행과 서명 격리는 앱 저장소가 아니라 플랫폼 SLA에 속합니다.
단순 xcodebuild와 비교하면 공증 단계는 가시성과 멱등성을 강조합니다. 동일 바이너리 반복 제출, 요청 식별자 주변의 멱등 의미론, 사건에 붙는 재생 가능한 셸 명령입니다. 이 셋을 Runbook에 넣어야 원격 Mac이「컴파일할 수 있다」에서「서명·공증·감사할 수 있다」로 올라갑니다.
야간 Archive와 주간 PR이 같은 호스트를 쓴다면 공증 Job을 컴파일 집약 Job에서 분리하세요. 공증은 네트워크 지터와 Apple 측 큐에 민감하고 CPU 바운드 빌드와 섞으면 꼬리 지연이 커집니다. GitLab resource_group이나 Actions 동시성 상한과 같은 패턴이며 리소스 이름은 사람이 읽기 쉬운「notarization slot」이 좋습니다.
공급자가 안정적인 이그레스 IP나 리전 선택을 제공하면 RTT와 TLS 가로채기 정책을 인수 테스트에 넣습니다. Apple 엔드포인트 트래픽을 복호화하는 기업 프록시는 전형적인「컴파일은 녹색, 공증은 적색」근본 원인입니다.
운숙성에는 Xcode와 함께 notarytool CLI를 버전 관리하는 것도 포함됩니다. Apple은 Xcode와 CLT로 업데이트를 배포하므로 내부 변경 로그에 동작을 고정하면 이미지 갱신 후 깜짝 플래그 변경을 피할 수 있습니다. API 키는 일정에 따라 로테이션하고 어떤 issuer가 어떤 팀에 매핑되는지 문서화하여 사고 대응 시 p8을 추측하지 않게 합니다.
마지막으로 공증 텔레메트리를 컴파일 시간과 같은 대시보드에 연결합니다. 제출 시간, 폴링 횟수, staple 시간, 디스크 여유 비율을 1급 시계열로 추적하면 모든 릴리스 브랜치에서 공증을 켠 뒤「CI가 느려졌다」는 질문에 용량 계획을 정직하게 설명할 수 있습니다.
한 장의 표로 모든 조직을 닫을 수는 없지만 사용자가 바이너리를 어떻게 받는지를 축으로 삼으면 리뷰가 빨라지고 인수 기준도 테스트 가능해집니다.
| 관점 | 직접 .dmg/.zip | 엔터프라이즈 포털 | TestFlight / App Store |
|---|---|---|---|
| 공증 제출 | 대개 필요: 기본 경로에서 Gatekeeper가 검증 가능한 티켓을 기대 | 필요: MDM 또는 포털 서명 정책과 정렬 | Apple 호스팅 배포가 지배적이며 로컬 stapler 기대는 직접 다운로드와 다름 |
| stapler staple | 강력 권장: 오프라인 설치 시 번들 안에 티켓 동봉 | 포털이 다시 zip하는지에 따름: 재패키징은 재공증 또는 정책 변경을 강요할 수 있음 | 「로컬 빌드마다 staple」과 같지 않음: 릴리스 채널을 따름 |
| 실패 파급 | 사용자 격리 프롬프트와 지원 부담 | 컴플라이언스 필드와 보안 사고 검토 가능성 | 종종 업로드·처리 큐로 나타나며 CI 공증과 동형이 아님 |
| 원격 Mac 이점 | 전용 디스크와 안정 이그레스: notary zip과 로그 보존 용이 | 내부 아티팩트 스토어와 인접 배치 시 전송 시간 단축 | Fastlane에 넘김: 공증과 업로드 역할 분리 |
| 흔한 오해 | 「Accepted」면 더블클릭이 항상 성공이라 가정하고 staple 시점을 놓침 | 백신이 페이로드를 다시 써 티켓 무효화 | 데스크톱 notarytool 경험을 App Store Connect 처리 지연에 그대로 적용 |
공증 맥락에서「VPS처럼 Mac을 빌린다」는 것은 재현 가능한 제출 평면을 산다는 뜻입니다. 고정 사용자, 예측 가능한 디스크 여유, 워크 트래커에서 submission id를 빌드 지문에 묶는 상태기입니다.
notarytool과 폐기 경로를 대비할 때 유지보수 창을 정의합니다. GUI 세션에 의존하는 스크립트가 남아 있는지, 모든 호출자가 JSON과 구조화 로그를 내는지.「완료」는 한 저장소가 잠시 녹색인 것이 아니라 CI 템플릿과 내부 스캐폴드가 전 플릿에서 갱신된 상태입니다.
멀티 리전이라도 노드별 이그레스 경로와 프록시 정책을 문서화합니다. 업로드 지역성은 컴파일 농장만큼 중요하지 않지만「도쿄 빌드, 실리콘밸리 공증」 라우팅을 데이터 처리 메모 없이 두면 컴플라이언스에 놀라움이 생깁니다.
보안 검토 패키지에는 한 페이지 결정 기록을 첨부합니다. 선택한 채널, staple 여부, API 키 로테이션 소유자, 깨끗한 VM에서 티켓을 검증하는 명령입니다. 스크린샷만보다 오래 갑니다.
순서는 먼저 신원과 키, 다음 산출물과 제출, 마지막 동시 실행을 강조합니다.재현 가능 빌드의 지문 스크립트와 맞춰 제출과 사후 분석을 모두 가능하게 합니다.
전용 CI 사용자와 로그인 기준선 생성: 개인 Apple ID와 공유하지 않습니다. 긴 폴링을 방해하지 않는 화면 잠금 정책을 확인합니다.
API 키와 notarytool 자격 증명 설치: p8, Issuer ID, Key ID 삼총사. 파일은 CI 사용자에게 읽기 전용.p8을 평문으로 커밋하지 않습니다.
파이프라인에서 업로드 가능한 산출물 생성: .app을 올바르게 서명하고 zip/dmg 경로에 파이프라인 id를 넣고 SHA256을 빌드 로그에 출력합니다.
submit 후 submission id 캡처: --wait 또는 사용자 정의 폴링. Apple 상태 객체를 산출물 디렉터리에 유지합니다.
로그 저장 및 실패 분류: Invalid면 상세 로그를 가져옵니다. 티켓에서 xcodebuild -version과 git commit을 연관시킵니다.
배포 정책에 따라 staple 및 검증: 포털이나 객체 스토어에 올리기 전에 stapler validate와 깨끗한 VM 설치 행렬을 실행합니다.
ZIP_PATH="dist/MyApp.${CI_PIPELINE_ID}.zip"
xcrun notarytool submit "$ZIP_PATH" \
--key "./AuthKey_XXXXX.p8" \
--key-id "$ASC_KEY_ID" \
--issuer "$ASC_ISSUER_ID" \
--wait \
--output-format json > "logs/notary-${CI_PIPELINE_ID}.json"
# 실패 시 상세(json에서 submission id 파싱)
# xcrun notarytool log <submission-id> --key ... > "logs/notary-detail.txt"
xcrun stapler staple "dist/MyApp.app"
참고: 동일 파이프라인이 App Store Connect에도 업로드한다면 Fastlane과 CI 인수인계를 읽고 API 키 역할(Developer 대 App Manager)과 notarytool 최소 권한을 변수 표에 적어 만능 키를 피하세요.
Xcode나 macOS 대규모 업그레이드 날에는 먼저 최소 서명 번들로 카나리아 공증을 수행해 notarytool과 stapler를 끝까지 검증한 뒤 애플리케이션 저장소를 엽니다. 골든 이미지 롤백과 보완합니다.
공급자가 스냅샷을 제공하면 스냅샷에 공증 툴체인 버전을 태그합니다. Xcode 빌드 번호, CLI 도구 버전, 알려진 notarytool 동작 변경입니다. 팀 전체가「미스터리 기본 플래그」퇴행을 함께 디버깅하지 않게 합니다.
산출물 보존은 컴플라이언스와 연결합니다. notary JSON과 stapler 출력을 수개월 보관해야 하는 팀도 있습니다. 객체 스토리지의 IPA 옆에 둘지 전용 감사 버킷에 생명주기 규칙을 둘지 일찍 결정하세요.
흔한 실수는「동시에 몇 개의 xcodebuild가 들어가는가」를 공증에 그대로 복사하는 것입니다. 실제로는 업로드 대역폭, Apple 측 큐, zip CPU, 키체인 잠금 해제가 단계마다 지배합니다.
notary_slots를 명시적으로 정의합니다. 예를 들어 원격 Mac당 동시 submit은 최대 1~2개, 나머지는 대기열. 벽시계 타임아웃과 허용 큐 SLA를 문서화합니다.SwiftPM과 CocoaPods 디스크 거버넌스와 교차합니다. 공증용 임시 zip은 크므로 DerivedData와 별 볼륨이나 디렉터리에 두어 야간 배치에서 시스템 디스크를 채우지 마세요.
주의: 디스크가 안전 임계값 아래인데 공증 작업을 계속 밀어 넣지 마세요. 반쯤 쓰인 zip은 재현하기 어렵게 업로드에 실패합니다. 스케줄을 멈추고 감사 가능한 삭제 목록으로 정리한 뒤 재개합니다.
재시도 정책을 나눕니다. 네트워크 순간 끊김에는 짧고 상한 있는 재시도, Apple 혼잡 신호에는 분 단위 백오프와 상한으로 속도 제한을 건드리지 않게 합니다. 모든 재시도는 submission id와 산출물 해시를 로그해「잘못된 세대 staple」사고를 막습니다.
중앙 프록시는 Apple 엔드포인트에 대한 명시 허용 목록과 TLS 우회 규칙이 필요합니다. 그렇지 않으면 컴파일은 모두 녹색, 공증은 모두 적색이고 증거는 프록시 장비에만 남습니다.
노트북에서 가끔 Archive하는 것과 비교하면 전용 원격 Mac은 24/7 예측 가능한 환경과 고정 SSH 운영면을 삽니다. 플랫폼은 공증 Runbook, 디스크 워터마크, 키 로테이션을 동일 노드 프로필에 붙일 수 있고 개발자 머신이 제각각 표류하지 않습니다.
자가 치유 에이전트를 도입할 때 진행 중인 notary 작업 공간을 삭제하지 않도록 합니다. 임대나 파이프라인 인식 경로로 삭제 작업을 보호해 자동화가 stapler 단계와 경주하지 않게 합니다.
아래는 내부 정렬용입니다. 임계값은 번들 크기와 동시성에 맞춰 조정하세요. 비율은 일반적인 플랫폼 관행을 반영하며 SLA를 굳히기 전에 자사 환경에서 재측정하세요.
--wait에 명시적 상한과 알림을 둡니다.submission id, 산출물 SHA256, xcodebuild -version을 동일 산출물 번들에 남겨 팀 간 재생이 가능하게 합니다.사무실 노트북은 수면 정책, VPN 지터, 개인 키체인에 시달립니다. 순수 Linux는 Apple 서명 체인을 호스트할 수 없습니다. 작업을 전용·상시 가동·SSH 도달 가능한 원격 Mac으로 옮기고 notarytool과 stapler를 템플릿화하면「빌드를 낼 수 있다」에서「증명·감사·인수인계할 수 있다」로 바뀝니다. 즉흥 예비 하드웨어나 불투명한 가상화 스택은 일관된 SSH, 투명한 디스크 단계, 재현 가능한 노드 프로필이 부족해 통제가 어렵습니다. 이러한 운영 프리미티브를 한 제품으로 묶은 NodeMini 클라우드 Mac Mini 렌탈이 안정적인 iOS CI/CD와 AI 에이전트 자동화에 보통 더 잘 맞습니다. 사양과 가격은 요금 페이지를 보고 온보딩은 헬프 센터로 마무리하세요.
이 Runbook을 내부 릴리스 등급에 묶습니다. 핫픽스, 스테이징, 프로덕션 레인은 공증 동시 실행, 로그 보존, staple 검증 행렬을 달리해도 파이프라인 전체를 포크하지 않아도 됩니다.
Apple은 API 키 기반 notarytool을 권장합니다. JSON 출력, 스크립트 가능한 폴링, 명확한 오류는 원격 Mac의 대화형 Apple ID 세션보다 CI에 적합합니다. 노드 사이징은 요금 페이지를 참고하세요.
채널에 따라 다릅니다. 직접 다운로드는 오프라인 Gatekeeper 검사를 위해 보통 staple이 필요합니다. App Store와 TestFlight는 Apple 호스팅 체인을 따릅니다. 네트워크와 접근은 헬프 센터를 보세요.
임시 디렉터리 경합, 속도 제한, 키체인 혼선입니다. notary_slots를 제한하고 작업 디렉터리를 버킷화하며 재현 가능 빌드 및 엔터프라이즈 빌드 풀의 키체인 계약과 일치시키세요.