Apple notarytool 기업 CI는 어떻게 구축할까? 2026 배포 가이드

CI 제출은 성공했는데 배포 파일의 공증 상태와 티켓 처리가 확인되지 않습니까?

이번 주에는 빌드·서명, 공증 제출, 상태 확인, 티켓 처리, 최종 검수를 서로 추적 가능한 단계로 나누세요. Xcode 빌드나 stapler가 필요한 단계는 macOS에서 검증하고, Notary API는 제출과 상태 조회의 일부에만 검토하세요.

이 글은 Mac App Store 밖에서 macOS 앱을 배포하는 팀을 위한 안내입니다. CI 플랫폼과 인증 정보를 관리하는 IT 담당자, Developer ID 서명부터 출시 파일 검수까지 책임지는 엔지니어가 대상입니다.

배포 경계를 먼저 정하면 CI 설계가 달라집니다

Apple notarytool 기업 CI를 설계할 때는 먼저 배포 경로와 공증 대상부터 확정해야 합니다. Mac App Store 외부 배포용 Developer ID 산출물에는 서명, 공증, 배포 검수를 연결하세요. Mac App Store 배포는 같은 공증 경로로 취급하지 않습니다. Apple은 공증을 App Review와 같은 절차로 설명하지 않습니다. Apple의 macOS 소프트웨어 공증 안내와 Developer ID 배포 문서를 기준으로 대상 경계를 확인하세요.

먼저 실제 전달물이 앱인지, 설치 패키지인지, 디스크 이미지인지 정하세요. 그 다음 산출물 형식에 맞춰 제출, 티켓 처리, 다운로드 후 검수 방법을 정합니다. 이 구분 없이 압축 파일과 앱 번들을 같은 방식으로 다루면, 공증 승인은 받았어도 최종 전달물 검수가 빠질 수 있습니다.

notarytool은 명령줄에서 제출과 상태 확인을 자동화하는 경로입니다. Notary API를 쓰더라도 Xcode 빌드나 macOS 서명, stapler가 필요한 과정까지 자동으로 다른 운영체제로 옮겨지는 것은 아닙니다. Apple은 Notary API로 제출과 상태 확인을 수행하는 방법도 제공합니다. Notary API 제출 안내를 검토하되, Mac CI와 API의 책임을 분리해 설계하세요.

첫 단계: 출시할 서명 산출물을 고정합니다

공증 대상은 CI 작업이 아니라 실제로 배포할 산출물입니다. 빌드 성공만으로 서명 상태나 배포 적합성이 보장되지는 않습니다. 아래 항목을 한 작업 기록에 연결해 두세요.

• 코드 변경 식별 정보와 CI 작업 기록
• 사용한 서명 신원과 서명 결과
• 공증에 제출한 파일과 출시 대상으로 지정한 파일
• 빌드·서명·공증 각 단계의 실행 결과와 담당자

Developer ID 서명에 Hardened Runtime이 필요한 조건과 예외를 확인하고, Apple 문서에 맞춰 서명 설정을 점검하세요. Hardened Runtime 설정 안내는 해당 실행 환경의 요구 사항을 판단하는 기준입니다. 개발용 서명으로 만든 앱을 그대로 배포해도 되는지는 이름만 보고 결정하지 말고, 실제 배포 경로와 서명 설정을 대조해야 합니다.

Xcode Organizer는 작업자가 산출물과 제출 상태를 직접 확인하기에 편리합니다. 반면 스크립트 기반 흐름은 반복 가능한 CI 단계와 기록 관리에 적합합니다. 두 방식 중 하나를 선택하더라도 동일한 최종 파일을 대상으로 검수해야 합니다.

인증 정보를 작업 범위에 맞게 분리합니다

notarytool 인증을 설정하기 전에 팀이 사용할 인증 방식을 정하세요. App Store Connect API 키를 쓰는 경우에는 키의 생성과 권한을 Apple 안내에 맞춰 구성해야 합니다. API 키 생성 및 권한 문서를 보고, 다른 인증 방식을 같은 절차인 것처럼 섞지 마세요.

CI 설정에서는 인증 정보가 저장되는 위치, 값을 읽을 수 있는 작업, 접근을 관리하는 담당자를 명확히 구분하세요. 저장소의 스크립트나 설정 파일에 값을 직접 기록하는 대신 CI 비밀 정보 기능을 이용하고, 공증 제출이 필요 없는 작업에는 해당 정보를 전달하지 않는 편이 좋습니다. 로그와 오류 출력에서 민감한 값이 노출되지 않는지도 실패 경로를 포함해 확인하세요.

인증 정보의 발급·교체·폐기 책임을 정해 두면, 담당자 변경이나 작업 흐름 수정 때 접근 권한을 다시 검토할 수 있습니다. 이는 Apple이 보장하는 서비스 기능이 아니라 팀이 정해야 할 운영 통제입니다.

제출 뒤에는 완료 상태와 로그를 확인합니다

CI에서 적합한 산출물을 제출한 뒤에는 반환된 submission ID를 보관하세요. 이 식별자를 빌드 작업 기록과 연결하면 상태 확인과 실패 원인 분석이 같은 산출물을 기준으로 이뤄집니다. Apple은 notarytool 기반 흐름에서 제출 상태와 로그를 확인하는 방법을 안내합니다. 공증 작업 흐름 사용자 지정 문서를 따라 제출 결과를 기록하세요.

파일 업로드가 끝났거나 명령이 정상 종료됐다는 사실만으로 공증 완료를 판정하지 마세요. CI 문턱은 제출 접수, 처리 중, 완료, 실패 상태를 구분하고, 최종 상태를 확인한 뒤 다음 배포 단계로 넘기도록 구성해야 합니다. 실패하면 Apple 반환 로그에서 문제 파일과 오류 내용을 확인하고, 서명 설정 및 제출 파일이 출시 대상으로 지정한 파일과 같은지 대조하세요.

자주 묻는 운영 판단

Q. Apple notarytool은 Mac CI에 어떤 순서로 연결해야 하나요?
A. 먼저 배포용 산출물의 서명을 완료하고, 그 파일을 제출한 다음 submission ID와 최종 상태를 보관하세요. 실패 시에는 반환 로그를 작업 기록에 연결해 원인을 추적합니다. 공증 결과 확인 뒤에도 티켓 처리와 최종 파일 검수 단계를 별도로 둬야 합니다.

Q. CI 인증 정보를 스크립트에 넣어도 되나요?
A. 인증 정보는 스크립트와 저장소에 직접 쓰지 말고 CI의 비밀 정보 저장 기능으로 관리하세요. 공증 작업에만 값이 전달되도록 권한을 제한하고, 로그에 값이 출력되지 않는지 확인합니다. 인증 정보의 교체와 폐기 담당자도 운영 절차에 정해 두세요.

Q. 제출 결과가 Invalid이면 어떤 자료를 먼저 확인하나요?
A. submission ID에 연결된 공증 로그를 먼저 확인하세요. 문제가 보고된 파일을 기준으로 서명 상태, Hardened Runtime 설정, 제출물과 배포물의 일치 여부를 점검합니다. 수정 전후의 파일과 CI 작업 기록을 보존하면 같은 실패를 반복하지 않고 원인을 비교할 수 있습니다.

Q. 승인된 배포 파일은 stapler 처리 없이 전달해도 되나요?
A. 무조건 생략하지 말고 배포 형식과 Apple 지침에 맞춰 판단하세요. 지원되는 대상은 티켓을 처리한 뒤 실제 전달 파일을 다시 검수합니다. ZIP 파일 자체에는 stapling할 수 없으므로, ZIP 안의 앱이나 적합한 배포 산출물을 기준으로 단계를 구성해야 합니다. Apple의 공증 작업 흐름 문서에서 형식별 경계를 확인하세요.

Q. Notary API를 도입하면 Mac CI가 필요 없어지나요?
A. 그렇지 않습니다. Notary API는 공증 제출과 상태 조회의 일부를 처리할 수 있지만, Xcode 빌드와 macOS 서명, 필요한 stapler 작업은 별도로 검토해야 합니다. API 적용 전 각 단계의 입력과 출력을 적고, 실제 파이프라인에서 Mac이 필요한 작업을 분리해 확인하세요. Notary API 제출 설명도 함께 참고하세요.

마지막 단계: 최종 파일을 기준으로 방출 여부를 결정합니다

공증 승인은 출시 전체가 끝났다는 뜻이 아닙니다. 배포 형식에 맞는 티켓 처리를 하고, 사용자가 받을 최종 파일에서 서명과 파일 무결성을 검수하세요. 실패한 경우에는 submission ID, Apple 반환 로그, 빌드 식별 정보, 서명 결과, 수정 내용을 함께 보관해야 추후 재현과 감사를 지원할 수 있습니다.

배포 방식 선택 도구

아래 조건을 위에서부터 확인하고, 처음 해당하는 경로를 선택하세요.

• [ ] Xcode로 빌드하거나 macOS 서명 또는 stapler 작업이 필요합니다.
  해당한다면 이 작업을 macOS CI에서 실행하고, 최종 배포 파일까지 검증하세요.

• [ ] 빌드와 서명은 Mac에서 수행하지만 공증 제출과 상태 조회는 별도 구성할 수 있습니다.
  해당한다면 Notary API를 시범 적용해 제출 입력, 상태 응답, 인증 권한을 실제 파이프라인에서 확인하세요. Mac 실행 단계는 유지합니다.

• [ ] 제출은 완료되지만 submission ID, 최종 상태 또는 Apple 반환 로그가 산출물과 연결되지 않습니다.
  해당한다면 API 전환을 미루고 먼저 추적 정보와 실패 기록을 보완하세요. 완료 상태 확인 전에는 출시 단계로 넘기지 마세요.

• [ ] 인증 정보를 공증이 필요 없는 작업까지 읽을 수 있거나 로그 노출 여부를 확인하지 못했습니다.
  해당한다면 배포 방식을 바꾸기 전에 접근 권한과 비밀 정보 처리부터 정비하세요.

• [ ] 장기간 이어지는 작업량이 예측 가능하거나 물리 장치 연결이 필요합니다.
  해당한다면 임시 원격 환경보다 자체 Mac 운영을 우선 비교하세요. 반대로 Mac이 필요한 작업이 간헐적이고 임시 실행 환경을 찾는다면 원격 Mac을 검토할 수 있습니다.

실제 파이프라인 한 번을 처음부터 끝까지 실행해 빌드, 서명, 제출, 상태 확인, 티켓 처리, 배포 파일 검수의 증거를 남기세요. 각 단계의 입력과 출력, 실행 책임자를 확인해야 CI가 승인 여부를 정확히 판정할 수 있습니다.

Mac CI를 직접 운영할지 임시로 확보할지 판단합니다

자체 Mac CI는 하드웨어와 운영체제 업데이트, 고장 대응을 직접 맡아야 하고, 사용량이 들쑥날쑥하면 유휴 장비가 생길 수 있습니다. 개발자별 Mac을 마련하면 장비별 환경 차이를 관리해야 하며, 공용 장비는 작업과 자격 증명의 접근 경계를 설계해야 합니다. 반대로 지속적이고 예측 가능한 부하나 물리 인터페이스가 필요한 팀은 자체 장비가 더 알맞을 수 있습니다.

원격 Mac은 Mac 환경이 필요한 빌드나 배포 검증을 임시로 수행할 때 후보가 될 수 있습니다. VPSMAC의 원격 Mac 제공 항목에서 현재 확인 가능한 제공 정보를 먼저 살펴보세요. 실제 운영에 앞서 네가 사용할 Xcode와 stapler 작업을 실행할 수 있는지, 인증 정보를 팀 정책에 맞게 격리할 수 있는지 직접 검증해야 합니다. 장기 상시 부하나 물리 연결 장치가 필수라면 임대보다 자체 Mac을 우선 비교하세요.

현재 장비의 교체·수리 부담과 유휴 시간, 팀별 환경 관리가 병목이라면 필요한 기간에만 원격 Mac을 쓰는 선택이 운영 방식에 맞을 수 있습니다. 반대로 장기간 계속 쓰거나 물리 장치 연결이 필요한 작업은 자체 장비가 더 타당할 수 있습니다. 도입 전 VPSMAC의 원격 Mac 선택 항목에서 확인 가능한 조건을 검토하고, 공증 파이프라인의 실제 작업으로 적합성을 판단하세요.