Apple 공증 CI 실패, 어떻게 진단할까? 2026 수정 가이드

CI의 업로드 성공만으로 배포 승인을 내리지 마세요. Apple 공증은 제출, 처리, 수락 확인, 필요한 경우의 티켓 부착과 최종 배포 파일 검증을 구분해서 봐야 합니다. Apple은 macOS 소프트웨어의 공증 절차와 제출 가능한 파일 형식을 공식 공증 안내에서 설명합니다.

오류가 나타난 시점을 기준으로 다음처럼 분류합니다.

• 업로드 단계에서 중단됨: 제출 요청이 접수되지 않았을 수 있습니다. CI가 출력한 제출 식별자와 명령 종료 결과를 확인하고, 요청이 실제로 생성됐는지부터 조사합니다.
• 요청은 접수됐지만 상태가 수락이 아님: 업로드 성공과 공증 처리 결과를 혼동하지 않아야 합니다. 제출 식별자로 상태를 조회하고, 제공되는 로그를 확인합니다. Notary API의 상태 조회와 로그 설명을 기준으로 요청 결과를 대조하세요.
• 공증은 수락됐지만 배포 파일 검증이 실패함: 공증 결과와 티켓 부착, 최종 파일의 Gatekeeper 검증은 서로 다른 확인 항목입니다. 실제로 배포할 파일까지 검사해야 합니다.

notarytool에서 성공으로 보이는 출력이 어떤 단계의 성공을 뜻하는지 CI 작업 로그와 함께 확인해야 합니다. 업로드 명령이 정상 종료됐다는 사실만으로 공증 수락을 판정하지 마세요.

Developer ID 앱 서명, 설치 패키지 서명, 공증 요청에 쓰는 인증 정보는 같은 요소가 아닙니다. 앱에 적용된 서명은 유효해도 제출 인증 정보가 거부될 수 있고, 반대로 제출이 접수돼도 앱의 서명이나 서명 체인 문제로 공증이 통과되지 않을 수 있습니다. Apple의 코드 서명 서비스 설명과 공증 관련 일반 문제 안내를 오류 원문과 함께 확인하세요.

다음 항목을 분리해 기록합니다.

• 앱 서명 확인: 공증 요청에 올린 최종 배포 파일이 의도한 서명으로 서명됐는지 검사합니다. 중간 빌드 산출물 검사만으로 최종 압축 파일의 상태를 대신 판단하지 않습니다.
• 제출 인증 정보 확인: CI 서비스 계정이 실제 제출에 사용하는 자격 증명과 권한을 확인합니다. 인증 정보가 누락됐는지, 실행 환경에서 해당 정보에 접근할 수 있는지 살핍니다.
• 오류가 가리키는 대상 확인: 서명 거부 메시지인지, 인증 정보 오류인지, 네트워크 제출 오류인지 원문을 구분합니다. 세 범주를 모두 맥 노드의 문제로 단정하면 불필요한 노드 교체나 인증서 변경으로 이어질 수 있습니다.

자동화 로그에는 제출 식별자와 오류 맥락을 남기되, 비밀 키나 민감한 인증 값이 그대로 출력되지 않는지도 검토합니다. 자격 증명이 어디에서 사용됐는지 확인할 수 있도록 서비스 계정과 Keychain 접근 기록을 관리하세요.

공증 전 검사는 프로젝트나 중간 앱이 아니라 실제 제출·배포에 쓰는 파일을 대상으로 해야 합니다. Apple의 맥 소프트웨어 패키징 및 배포 안내와 공증 로그를 함께 참고해 패키징 결과와 서명 상태를 확인하세요.

점검 순서는 다음과 같습니다.

• 공증 제출에 선택한 파일이 배포 형식과 일치하는지 확인합니다. 앱 번들, 디스크 이미지, 설치 패키지처럼 파일 형식에 따라 검사와 배포 과정이 달라질 수 있습니다.
• 서명 누락이나 유효하지 않은 서명에 관한 로그가 있는지 확인합니다. 오류가 특정 구성 요소를 가리키면 그 구성 요소의 서명 상태를 조사합니다.
• Entitlements가 배포 목적과 맞는지, 앱에 필요한 항목이 의도한 대로 설정됐는지 검토합니다.
• 패키징이나 서명을 수정했다면 수정된 최종 파일을 다시 검사하고, 이전 파일의 공증 결과를 새 파일에 그대로 적용하지 않습니다.

Apple 로그가 파일 내부 구성이나 서명 문제를 지목한다면 먼저 해당 산출물을 고치세요. 로그 근거 없이 Developer ID 인증서 전체를 교체하거나 서명 설정을 일괄 변경하는 방식은 원인 확인을 어렵게 만들 수 있습니다.

공증 상태가 아직 처리 중이거나 로그를 통해 원인을 판단하기 어렵다면, 새 제출을 만들기 전에 현재 요청의 맥락을 보존합니다. Apple의 Notary API 안내는 제출 식별자를 이용한 상태 확인과 로그 조회를 다룹니다. 이 과정에서 처리 시간에 대한 고정된 기대를 세우거나, 로그가 즉시 나타나지 않는 이유를 임의로 단정하지 마세요.

재시도 전에 다음 기록을 확인합니다.

• CI 작업의 전체 실패 단계와 해당 명령의 종료 결과
• 공증 제출 식별자와 상태 응답
• 확인 가능한 경우 Apple 공증 로그
• 제출한 파일의 이름과 빌드 식별 정보
• 사용한 서비스 계정과 자격 증명 접근 기록

같은 파일의 유효한 요청이 이미 있는지, 파이프라인이 제출 식별자를 잃어버린 것은 아닌지 확인한 뒤 재시도를 결정합니다. 네트워크 연결이나 제출 인증 오류가 확인되면 그 부분만 수정하고, 파일 서명이나 패키징 오류가 확인되면 수정된 배포 파일을 대상으로 새 제출이 필요한지 판단하세요.

공증 실패를 이유로 전체 빌드를 즉시 반복하지 마세요. 기존 요청 상태와 로그를 먼저 보존해야 동일한 오류가 재발하는지, 새 제출이 필요한지 구분할 수 있습니다.

공증 수락은 티켓이 최종 전달 파일에 부착됐다는 뜻과 같지 않습니다. 배포 형식에 맞는 절차를 Apple의 공증·패키징 안내에 따라 선택하고, 필요한 경우 stapler로 티켓을 부착한 뒤 최종 파일에서 검증 결과를 확인합니다.

검수할 때는 다음을 확인합니다.

• 수락 결과와 연결된 제출 식별자를 보관합니다.
• 배포 형식에 맞는 티켓 부착 방법을 선택합니다.
• 부착 작업의 명령 결과와 최종 검증 출력을 CI 산출물에 남깁니다.
• 실제 배포할 파일을 대상으로 검증하고, 이후 파일을 다시 패키징하거나 수정했다면 그 파일을 다시 확인합니다.

CI에서 공증이 성공했다고 보고됐더라도, 배포 단계에서 사용하는 파일이 다른 경로의 파일인지 점검해야 합니다. 서명 및 공증이 완료된 산출물과 실제 업로드·배포 대상이 일치해야 검수 기록이 유효합니다.

다음 판단 기준으로 재서명, 재제출, 환경 수정을 구분하세요.

• 공증 상태가 수락이 아니고 로그가 서명 또는 파일 구조를 가리키면: 해당 최종 파일의 서명·Entitlements·패키징을 수정하고, 수정된 파일을 다시 검증합니다.
• 제출 인증 정보나 권한 오류가 확인되면: 서비스 계정, CI 실행 환경의 Keychain 접근, 자격 증명 설정을 점검합니다. 앱을 무조건 다시 빌드하지 않습니다.
• 요청 상태가 불명확하거나 로그가 아직 원인을 설명하지 못하면: 제출 식별자와 응답을 보존하고 Apple 개발자 시스템 상태를 확인합니다. Apple 개발자 시스템 상태 페이지에서 서비스 관련 상태를 점검하되, 고정 처리 시간을 가정하지 않습니다.
• 공증 수락 뒤 티켓 검증이 실패하면: 수락 자체를 다시 시도하기보다 배포 파일 형식, 티켓 부착 결과, 최종 검증 대상을 확인합니다.
• CI 노드에서만 인증 정보나 네트워크 접근 문제가 반복되면: 서비스 계정·Keychain·네트워크 출구를 점검합니다. 서비스 상태가 정상이고 파일 관련 로그가 실패를 가리킨다면 원인은 노드보다 앱 산출물에 있을 수 있습니다.

출시 승인 전에는 아래 항목을 모두 확인하고 기록을 보관합니다.

• [ ] 최종 배포 파일의 서명 검사 결과를 저장했습니다.
• [ ] 공증 제출 식별자와 상태 응답을 저장했습니다.
• [ ] 공증 로그와 처리 결과를 확인했습니다.
• [ ] 필요한 티켓 부착 작업의 결과를 저장했습니다.
• [ ] 실제 배포 파일의 최종 검증 출력을 남겼습니다.
• [ ] 서비스 계정과 자격 증명 사용 기록을 확인했습니다.

원격 빌드 환경의 접근과 운영 조건은 NUKCLOUD 지원 안내에서 확인할 수 있습니다. 팀의 원격 맥 사용 방식과 제공 환경을 검토하려면 NUKCLOUD 원격 맥 서비스 안내도 참고할 수 있습니다. 노드가 온라인이라는 사실만으로 서명부터 최종 배포 파일까지의 검수를 대신해서는 안 됩니다.

업로드 성공만 확인되면 출시를 승인해도 되나요?
아니요. 공증 서비스의 처리 결과가 수락인지 확인하고, 배포 파일에 필요한 티켓 부착과 최종 검증까지 마쳐야 합니다.

공증 실패 때마다 전체 파이프라인을 다시 실행해야 하나요?
아닙니다. 제출 상태와 로그를 확인해 실패 단계를 특정한 뒤 해당 설정이나 파일만 수정합니다. 기존 요청의 상태와 식별자를 먼저 보존하세요.

앱의 서명 문제와 제출 인증 오류는 어떻게 구분하나요?
오류가 앱 서명·서명 체인을 지목하는지, 제출 자격 증명이나 권한을 지목하는지 공식 로그 원문으로 확인합니다. 서로 다른 문제이므로 같은 조치를 반복하지 않습니다.

공증 수락 후에도 최종 파일 검사가 필요한가요?
필요합니다. 배포 형식에 맞는 티켓 부착 여부를 확인하고, 실제 전달할 파일에서 검증 결과를 기록해야 합니다.

공증 장애가 CI 계정, Keychain 권한, 원격 노드의 실행 환경 문제로 좁혀졌다면 현재 방식의 관리 책임과 접근 통제를 함께 검토해야 합니다. 자체 맥은 물리 접근과 장기 고정 환경을 확보하기 좋지만, 장비 구매·유지보수와 교체 관리가 필요합니다. 범용 클라우드 환경은 기존 운영 체계에 맞추기 쉽지만, 실제 맥 하드웨어가 필요한 빌드 작업에는 맞지 않을 수 있습니다. 이와 비교해 NUKCLOUD의 원격 맥 임대는 실제 맥이 필요한 단기 검증이나 팀의 CI 환경 시험에 대안을 제공합니다. 다만 장기 고정 부하나 물리 포트가 필요한 작업이라면 자체 장비가 더 적합할 수 있으므로, 서명부터 최종 파일 검증까지 실제 업무로 환경을 먼저 평가하세요.