2026년 원격 Mac 헤드리스 공증 파이프라인: notarytool App Store Connect API vs 키체인 프로필 + stapler·notarytool log SSH 트러블슈팅 의사결정표·FAQ
공증을 “내 GUI 맥에선 되는데” 수준에서 끝내지 말고, 감사 가능한 파이프라인으로 바꿉니다. 먼저 notarytool 인증 방식을 고르고, 트리아지는 stapler와 notarytool log로 나눕니다. SSH로 돌리는 원격 Mac·CI 러너를 대상으로 비교표와 증상 우선 의사결정 매트릭스를 런북에 그대로 붙여 넣을 수 있게 정리했습니다.
1. 2026년에 notarytool을 기본으로 두는 이유
Apple은 레거시 altool에서 notarytool(Xcode·Command Line Tools에 포함)로 이전했습니다. 헤드리스 원격 Mac에서는 제출·히스토리·상세 로그를 한 CLI로 다룰 수 있어 스크립트·런북에 맞고, 불안정한 업로드 경로나 웹 클릭에 덜 의존합니다.
머릿속 모델은 세 단계로 고정하세요: 아티팩트 서명 → notarytool submit(제출 ID 보관) → 성공까지 폴링 → (선택) stapler staple로 디스크에 티켓 포함. 자격 증명을 어디에 두느냐가 SSH 환경에서 이 루프가 안정적인지를 가릅니다.
2. 두 가지 인증 경로: App Store Connect API 키 vs 키체인 프로필
2.1 App Store Connect API(Issuer ID + Key ID + .p8)
App Store Connect → 사용자 및 액세스 → 키에서 API 키를 만들고, .p8을 한 번만 내려받습니다. notarytool은 --key, --key-id, --issuer로 소비합니다. 전형적인 장점은 다음과 같습니다.
- 비대화형: Apple ID 비밀번호나 SMS/기기 2FA 없이 CI에 적합합니다.
- 순환·폐기: 키 수명 주기가 명확하고 유출 시 영향 범위를 줄이기 쉽습니다.
- 권한 범위: 역할 경계가 감사에 유리합니다.
운영적으로는 .p8을 잠긴 경로(권한 600)에 두거나 시크릿 매니저에서 주입하고, Git에는 절대 넣지 마세요. 자동화에서 여러 공급자·비밀을 겹칠 때도 “코드와 자격 증명 분리 + SSH에서 검증”은 같은 층위입니다. 구체 패턴은
2026년 OpenClaw 다중 모델·API 키 구성 실전: MiniMax/Qwen 등 Provider 연결, 원격 Mac SSH 트러블슈팅 체크리스트와 FAQ
에서 다룹니다.
2.2 키체인 프로필(notarytool store-credentials)
notarytool store-credentials로 Apple ID 또는 API 자료를 로그인 키체인에 이름 있는 프로필로 저장한 뒤, --keychain-profile "이름"으로 호출합니다. 대화형으로 한 번 설정하고 같은 사용자 세션에서 재사용할 때 잘 맞습니다.
원격 헤드리스에서는 SSH 비로그인 셸, 데몬, 동시 잡이 키체인 잠금 해제 상태나 로그인 키체인 소유 사용자를 어긋나게 하면 “수동은 되는데 파이프라인만 간헐 실패”가 납니다. 관리 경로를 제로트러스트 터널로 노출할 때는 빌드 비밀과 같은 표면에 두지 않는 편이 안전합니다. 분리 관점은 2026년 OpenClaw 게이트웨이 무노출 배포: Tailscale Serve/Funnel vs Cloudflare Tunnel(cloudflared) + 원격 Mac SSH 재현 절차·FAQ 와 맞닿습니다.
3. 의사결정표(런북에 복사)
| 축 | ASC API 키(.p8) | 키체인 프로필 |
|---|---|---|
| 헤드리스 / CI 적합도 | 높음: 플래그·환경 주입 | 중간: 잠금 해제·사용자 맥락에 의존 |
| 자격 증명 순환 | 키 교체 후 파이프라인 변수만 갱신 | 키체인 항목·프로필 재생성 |
| 동시 잡 | 잡마다 공유 .p8(권한·락 주의) | ACL·세션 경합이 흔함 |
| 컴플라이언스 / 감사 | Key ID·발급 흔적이 명시적 | 호스트·사용자 단위 부가 기록 필요 |
| 전형적 용도 | 공유 러너, 임대 Mac 노드, 다수 저장소 | 로그인 세션이 안정적인 단일 개발기 |
한 줄 요약: 2026년 팀 단위 원격 Mac 공증은 기본을 ASC API + .p8로 두고, 동일 macOS 사용자와 안정적인 키체인 잠금 해제를 보장할 때만 프로필 중심 흐름을 고려하세요.
4. stapler vs notarytool log: SSH에서의 트리아지 분리
역할이 다릅니다. stapler는 디스크에 있는 번들에 티켓이 있고 Gatekeeper 관점에서 일관되는지, notarytool log <submission-id>는 해당 제출에 대한 Apple 서버 측 판정과 구조화된 실패 사유입니다.
| 증상(SSH에서 흔함) | 우선 조치 | 이유 |
|---|---|---|
notarytool submit이 Invalid / Rejected |
notarytool log <id> 조회(또는 history로 id 확인) |
근본 원인은 서버 스캔 결과에 있음; stapler로는 안 보임 |
| 상태는 Accepted인데 배포물은 “공증 안 됨” | 배포 아티팩트에 stapler staple 후 stapler validate |
DMG/ZIP/중첩 앱에 티켓 누락이거나 unstapled 사본을 배포한 경우 |
| 빠른 게이트: “이 파일에 티켓 있나?” | stapler validate / spctl 계열 점검 |
API 왕복 없음; 프리플라이트에 적합 |
| 같은 스크립트가 “가끔 성공·가끔 실패” | 제출 ID를 고정해 로그 diff → 키체인·동시성·프록시 점검 | 플레이크는 자격 맥락·업로드 무결성에서 많음; 로그로 반복 원인과 환경 드리프트를 분리 |
5. FAQ: 헤드리스 공증 함정
Q1: CI가 키체인에 접근 못 하거나 프로필이 없다고 합니다
먼저 의심: 잡 사용자가 store-credentials를 실행한 사용자와 다르거나, 로그인체인이 잠겨 있음. 다음: ASC API 3종 세트로 전환; 프로필을 유지해야 하면 launchd로 러너를 올리고 잠금 해제를 명시하며 서명·공증 단계는 직렬화하세요.
Q2: Accepted인데 stapler 오류
먼저 의심: 스테이플 대상이 잘못됨(예: DMG로 다시 감싸기 전에 앱만 스테이플), 읽기 전용 경로·샌드박스 제한. 다음: Apple이 지원하는 스테이플 형식에 맞추고, 검증한 경로와 파이프라인이 동일 파일을 만지는지 확인하세요.
Q3: 로그에 서명·Hardened Runtime·엔타이틀먼트 언급
먼저 의심: 공증 전 서명과 선언된 엔타이틀먼트가 불일치(중첩 헬퍼 포함). 다음: 같은 원격 Mac에서 재현하고 codesign -dvvv·엔타이틀먼트를 비교해 수정 후 재제출—“로컬만 고쳤는데 CI는 옛 스크립트”를 피하세요.
Q4: 사내 프록시가 업로드를 망가뜨림
먼저 의심: 프록시가 Apple 업로드 엔드포인트를 차단하거나 MITM. 다음: 빌더에 예외 또는 우회; SSH에서 작은 제출로 TLS를 먼저 검증한 뒤 대용량 아티팩트를 올리세요.
이 파이프라인을 Mac mini에서 돌리는 이유
notarytool, codesign, stapler는 macOS 툴체인의 일급 구성 요소입니다. Apple Silicon Mac mini에서는 Apple이 공증에 기대하는 런타임·보안 스택을 그대로 쓰므로, 다른 OS에서 엣지 케이스를 다시 유도하기 어렵습니다. 통합 메모리와 대기 전력이 한 자릿수 와트 수준인 점은 상시 가동 원격 빌더에도 맞습니다—조용하고 발열도 낮으며 큐가 비어도 켜 두기 부담이 적습니다.
팀 단위로는 Gatekeeper·SIP·FileVault와 파일 권한 모델 덕분에 누가 어느 호스트에서 제출하는지 설명하기 쉬워, 일반 VM으로는 맞추기 힘든 컴플라이언스 서사가 됩니다. 아카이브 → 서명 → 공증을 한 줄로 묶었다면, 전용 Mac mini M4가 비용 대비 가장 현실적인 실물 앵커인 경우가 많습니다. 지금 원격 Mac을 확보해 이 런북을 꾸준히 초록 빌드로 이어 가 보세요.