Apple Silicon 클라우드 Mac iOS/macOS CI: codesign, Notarization, stapler·키체인 경계

핵심 요약

CI용 전용 키체인 파일을 만들고 배포용 인증서·개인 키를 넣은 뒤, 시크릿 스토어의 비밀번호로 잡 시작 시 잠금 해제—재부팅마다 달라지는 기본 로그인 키체인에 의존하지 않습니다.
--keychain / CODE_SIGN_KEYCHAIN을 명시하고, 빌드와 동일한 셸에서 security find-identity -v -p codesigning으로 신원을 확인합니다.
xcodebuild 아카이브·보내기 후 notarytool 제출 → 폴링 → stapler staple은 사용자가 실제로 받는 바깥쪽 zip·앱·dmg에 적용합니다. 안쪽 바이너리만 staple하는 실수가 흔합니다.
공증 업로드는 아웃바운드 경로에 민감합니다. 동일 호스트에서 VPN을 쓰면 기본 라우팅이 꼬일 수 있으니 WireGuard와 게이트웨이 페어링: 국경 초과 원격 제어 트러블슈팅—MTU, 비대칭 라우팅, DNS 분할·지연 관측(클라우드 Mac 리전·사양)에서 다룬 비대칭 라우팅과 함께 점검하세요.

노트북과 코드가 있는 개발자 작업 공간, 클라우드 Mac CI와 서명 워크플로를 상징 — 히어로 이미지는 참고용입니다. 실제 배포에는 `codesign -dv`, 공증 로그 발췌, 배포 아티팩트의 티켓 존재 여부로 검증하세요.

1. 무인 호스트에서의 키체인 경계

클라우드 Mac CI에서는 콘솔 앞에 사람이 없으므로, UI 승인이나 로그인 세션 키체인 기본값을 가정하면 이미지 갱신 후 간헐 실패합니다. 파일 키체인(예: ~/Library/Keychains/ci-signing.keychain-db)을 표준으로 두고 Apple Distribution 인증서와 개인 키를 가져온 뒤, 알려진 비밀번호로 잡 시작 시 security unlock-keychain -p "$KEYCHAIN_PASSWORD" "$KEYCHAIN_PATH"를 실행하세요. KEYCHAIN_PATH를 단일 진실 원천으로 두고 xcodebuild에는 OTHER_CODE_SIGN_FLAGS=--keychain "$KEYCHAIN_PATH" 등으로 전달합니다. Export 옵션 plist에 팀과 프로파일이 이미 박혀 있지 않다면 Developer ID와 Apple Distribution 신원을 한 체인에 섞지 않는 편이 안전합니다. 호스팅 러너의 큐 지연과 전용 Mac의 I/O·서명 처리량 차이는 팀 런북에 별도 표로 두고, 병렬 레인을 늘리기 전에 P95를 측정해 두세요.

2. codesign 층위: entitlements, Hardened Runtime, 중첩 번들

재현 가능한 서명은 매 빌드마다 동일한 entitlements plist와 프로비저닝 프로파일 해시를 의미합니다. Export 직후 앱 번들에 codesign --verify --deep --strict를 돌리고, PlugIns·Frameworks 안 헬퍼마다 팀 ID와 Hardened Runtime 플래그가 일치하는지 확인합니다. 불일치는 메인 앱은 깨끗해 보였다가 productbuild나 notarytool 단계에서만 errSecInternalComponent·errSecMissingEntitlement로 터지기도 합니다. .pkg를 만들 때는 구성 요소를 아래에서 위로 서명한 뒤, 런북에 적어 둔 설치자 인증서로 패키지를 서명합니다. 같은 머신에서 Docker 헬퍼를 쓸 때는 호스트 키체인을 사용자 맥락과 맞지 않는 컨테이너에 묶어 인증서는 보이는데 개인 키는 안 풀리는 상태를 피하세요. 자세한 마운트·디스크 예산은 Apple Silicon 클라우드 Mac에서 프로덕션 Docker: arm64/amd64 이미지, 바인드 마운트·빌드 캐시 문제 해결 핸드북(요금제 리소스 한계 포함)과 같이 봅니다.

3. Notarization과 stapler: 순서 고정

저장소 밖의 App Store Connect API 키(issuer, key ID, .p8 경로)로 notarytool을 쓰고, .p8 커밋은 피하세요. Gatekeeper가 평가할 바이너리 그대로(zip, 앱 번들, 공증 준비 .dmg 등)를 제출한 뒤 Accepted를 받기 전에는 staple하지 않습니다. xcrun stapler staple <경로> 후 stapler validate로 확인합니다. Apple이 성공을 돌려주기 전에 staple하거나, 바깥 아카이브를 다시 압축해 체크섬이 바뀌면 고객이 보는 해시와 공증 기록이 어긋납니다. API 키 순환과 submission ID는 변경 로그에 남겨 App Store Connect 이력과 CI 로그를 맞춥니다. 거절 시 notarytool log <submission-id>로 JSON 로그를 뽑아 첫 실패 규칙 ID를 티켓에 붙이세요.

# 예시: 제출 후 대기(프로파일명·경로는 프로젝트에 맞게 교체)
xcrun notarytool submit ./MyApp.zip --keychain-profile "AC_NOTARY" --wait
xcrun stapler staple ./MyApp.zip
xcrun stapler validate ./MyApp.zip

4. 최소 파이프라인 체크리스트

CI 키체인 잠금 해제 후 security find-identity로 신원 확인.
오래된 프로파일 진단 시에만 Derived Data 정리, 그 외에는 의존성 버전을 고정한 증분 빌드 선호.
고정된 ExportOptions.plist로 아카이브·보내기, dSYM 업로드는 공증과 분리.
Apple에 제출 → Accepted까지 폴링 → staple → validate → 아티팩트와 함께 체크섬 공개.

같은 호스트에서 Xcode와 Docker를 함께 쓰면 볼륨 마운트와 디스크 여유를 반드시 짝지어 점검합니다. 위 체크리스트는 앞서 링크한 Docker 핸드북과 함께 두면 운영 온콜이 한 페이지에서 끝납니다.

5. 증상·원인·조치(서명·공증 빠른 참고)

증상 / 로그 단서	가능성 높은 원인	권장 조치
서명 중 `errSecInternalComponent`	CI 키체인에서 개인 키 사용 불가, ACL 또는 비밀번호 불일치	키+인증서 재가져오기, 잡 안에서 키체인 잠금 해제, 명시적 `--keychain`
`No signing certificate found`	키체인 검색 순서 오류 또는 프로비저닝 프로파일 누락	`CODE_SIGN_KEYCHAIN` 설정, `~/Library/MobileDevice/Provisioning Profiles`의 프로파일 UUID 확인
Hardened Runtime 관련 공증 `Invalid`	배포에 허용되지 않는 entitlement, 서명되지 않은 중첩 헬퍼	Apple 문서와 entitlements diff, 중첩 번들 딥 검증
CI는 성공인데 Gatekeeper 격리 유지	배포물에 stapler 미실행, 공증 후 zip 재압축으로 티켓 무효	최외곽 전달물에 staple, validate, staple 이후 재포장 금지
`notarytool` 인증 오류	issuer·key ID 오류, 시계 어긋남, 폐기된 API 키	키 순환, NTP 동기화, JSON 키는 저장소 밖

6. 맺음말

서명·공증·staple은 하나의 상태 머신으로 다루세요. 각 단계의 입력은 이전 단계의 출력입니다. 키체인 경로, 프로파일 UUID, 공증 submission ID를 같은 런북 항목에 적어 두면 다음 담당자가 어떤 신원이 살아 있었는지 추측하지 않아도 됩니다. 체인이 안정되면 새 러너 이미지에서 콜드 스타트 빌드를 한 번 돌려 재부팅과 자격 증명 순환 이후에도 살아 있는지 증명하세요.