match 동기화는 끝났는데 원격 맥에서 서명 항목을 찾지 못하거나 Archive가 실패합니다.
가장 먼저 빌드 작업의 실행 계정과 키체인을 확인한 뒤, 인증서에 연결된 개인 키와 프로비저닝 프로파일이 프로젝트 설정에 맞는지 점검하세요. CI와 출시 작업은 이미 준비된 자산을 쓰는 읽기 전용 동기화부터 고려하고, 인증서를 바로 철회하거나 다시 만들지는 마세요.
이 글은 fastlane 빌드를 새 원격 맥으로 옮긴 독립 개발자, iOS 출시 작업을 운영하는 소규모 팀, 원격 Archive의 서명 문제를 진단하려는 개발자를 위한 안내입니다.
실행 환경과 서명 설정을 나눠 살펴보고, 실제 출시 구성을 이용해 복구 여부를 확인하는 방법을 설명합니다.
fastlane match 원격 맥 서명 실패는 동기화 다음 단계에서 갈립니다
fastlane match는 인증서와 프로비저닝 프로파일을 저장소에서 동기화할 수 있지만, 동기화 완료가 현재 빌드 작업의 서명 성공을 보장하지는 않습니다. fastlane 문서의 새 기기에서 자산을 동기화하는 설명을 기준으로 보면, 확인할 대상은 적어도 두 가지입니다. 필요한 파일을 가져왔는지, 그리고 실제 빌드 계정이 해당 자산으로 서명할 수 있는지입니다.
코드 서명에는 인증서만으로 충분하지 않습니다. Apple은 서명 인증서와 그에 대응하는 개인 키를 함께 다루며, 개인 키는 키체인에서 관리됩니다. 따라서 원격 맥의 인증서 목록에 항목이 있어도 현재 작업 계정에서 개인 키를 사용할 수 없다면 서명 단계에서 막힐 수 있습니다. Apple의 서명 인증서 안내와 코드 서명 인증서 기술 문서를 함께 참고하세요.
새 원격 맥에서는 실행 계정과 자산 저장 위치부터 확인합니다
첫 동기화가 실행된 계정과 Xcode 빌드 작업을 실행하는 계정이 다르면, 두 작업이 서로 다른 사용자 환경과 키체인을 볼 수 있습니다. 작업 디렉터리, 셸에서 전달된 환경 변수, fastlane 실행 위치도 함께 살펴보세요. 로그에는 어떤 계정으로 어떤 단계를 실행했는지 남기되, 비밀번호나 저장소 접근 키 같은 비밀값은 출력하지 않아야 합니다.
fastlane 문서는 match 저장소 접근 정보와 암호화된 자산을 다루는 방법을 안내합니다. match의 저장소와 자격 증명 설명을 확인하고, 원격 작업에서 저장소 접근과 복호화가 각각 성공했는지 구분해 기록하세요.
점검 기록은 다음처럼 비밀값을 제외한 상태만 남길 수 있습니다. 아래는 기록 형식의 예시이며, 실제 fastlane 출력이나 성공 결과를 뜻하지 않습니다.
작업 단계: match 동기화 / Archive / 내보내기
실행 계정: [계정 별칭]
프로젝트 타깃: [타깃 이름]
설정: [빌드 구성]
저장소 접근: 성공 / 실패
복호화: 성공 / 실패
서명 단계: 성공 / 실패
비밀값: 기록하지 않음
인증서는 보이지만 개인 키를 사용할 수 없는 환경
인증서가 있다는 사실과 그 인증서에 대응하는 개인 키가 현재 계정에 사용 가능하다는 사실은 별개입니다. 먼저 match 작업과 빌드가 같은 계정으로 실행되는지 확인하세요. 이어서 해당 계정이 사용하는 macOS 키체인에서 인증서와 개인 키가 연결되어 있는지 점검합니다. Apple은 코드 서명에서 인증서와 개인 키의 관계를 설명하며, 코드 서명 개요도 서명 자산을 구분해 이해하는 데 도움이 됩니다.
키체인에서 개인 키를 찾을 수 없다고 해서 곧바로 인증서를 철회하거나 다시 발급하는 것은 바람직하지 않습니다. 키체인 접근 권한, 실행 계정, 인증서가 동기화된 경로를 먼저 확인하세요. 계정이나 키체인이 다르다면 기존 인증서가 해당 사용자에게 보이지 않는 것이 원인일 수 있습니다. 원인을 구분하지 않은 채 자산을 바꾸면 정상적으로 서명 중인 다른 빌드에도 영향을 줄 수 있습니다.
참고: 인증서 이름만 확인하지 말고, 실제 Archive 작업을 실행하는 계정에서 서명에 필요한 개인 키를 쓸 수 있는지도 확인해야 합니다.
프로비저닝 프로파일이 있어도 프로젝트가 다른 구성을 선택할 수 있습니다
프로파일을 설치했다는 사실만으로 Xcode가 원하는 프로파일을 선택하는 것은 아닙니다. 프로젝트의 Bundle ID, 타깃, 빌드 구성, 배포 목적에 맞는지 각각 비교하세요. 앱 타깃과 확장 타깃처럼 서명 대상이 여럿이면, 한 타깃의 설정이 맞아도 다른 타깃에서 실패할 수 있습니다.
Apple의 코드 서명 빌드 설정 안내는 Xcode가 빌드 설정에 따라 서명 구성을 적용하는 방식을 설명합니다. App Store 배포용 프로파일의 용도와 조건은 App Store 프로비저닝 프로파일 안내와 대조하세요. match에서 프로파일을 가져왔는지와 실제 프로젝트가 그 프로파일을 선택했는지는 따로 확인해야 합니다.
원격 빌드 상황별로 실패 지점을 나눠 봅니다
| 상황 | 우선 확인할 항목 | 다음 조치 |
|---|---|---|
| 새 원격 맥에서 첫 동기화 | 작업 계정, 저장소 접근, 복호화 | 동기화한 계정과 빌드 계정이 같은지 확인합니다 |
| 인증서가 있지만 서명 실패 | 개인 키와 현재 계정의 키체인 | 해당 계정이 인증서에 연결된 개인 키를 사용할 수 있는지 점검합니다 |
| 프로파일 설치 후에도 실패 | 타깃, Bundle ID, 빌드 설정, 배포 용도 | 실제 Archive가 참조하는 설정과 프로파일을 대조합니다 |
| 로컬은 성공하고 CI는 실패 | 자격 증명 공급 경로와 읽기 전용 여부 | 저장소 접근, 복호화, 서명 단계를 분리해 확인합니다 |
| Debug는 성공하고 Archive는 실패 | Archive의 서명 구성과 배포 방식 | Archive 오류와 내보내기 오류를 구분해 조사합니다 |
읽기 전용 동기화는 준비된 자산을 쓰는 CI에 적합합니다
CI나 정식 출시 작업에서는 이미 준비된 자산을 동기화하는 흐름을 우선 고려할 수 있습니다. fastlane은 CI에서 match를 읽기 전용으로 사용하는 방법을 안내합니다. 예를 들어 명령 형식은 다음과 같습니다.
bundle exec fastlane match appstore --readonly
이 모드는 읽기 전용으로 동기화하는 선택이지, 빠진 개인 키를 복구하거나 잘못된 프로파일을 교체하는 수단이 아닙니다. 먼저 원격 작업이 자격 증명 저장소에 접근할 수 있는지, 필요한 복호화 정보가 안전하게 전달되는지 확인하세요. 접근이나 복호화가 실패한 경우와, 자산은 준비됐지만 서명이 실패한 경우를 같은 오류로 취급하지 않아야 합니다.
출시 작업을 처음 준비하는 단계와 일상적인 CI 실행도 구분해야 합니다. 서명 자산이 이미 준비된 정기 빌드에서는 읽기 전용 사용이 적합할 수 있습니다. 반면 새 자산을 준비해야 하는 상황이라면 읽기 전용 설정이 문제를 해결해 주지 않습니다. 자산을 변경할 필요가 있는지부터 따로 판단하세요.
읽기 전용 옵션은 저장된 자산을 안전하게 소비하기 위한 운용 방식입니다. 인증서나 프로파일의 적합성을 자동으로 판정하거나 고쳐 주지는 않습니다.
FAQ: 동기화 이후에 자주 놓치는 점
동기화가 성공했는데 서명 신원이 보이지 않는다면 어디부터 봐야 하나요?
동기화 작업과 빌드 작업의 실행 계정이 같은지 먼저 비교합니다. 그다음 빌드 계정의 키체인에 인증서뿐 아니라 대응하는 개인 키도 사용 가능한지 확인하세요. 두 항목이 정상이라면 타깃과 빌드 설정이 다른 서명 자산을 선택하는지 살펴봅니다. 자산 재생성은 이 점검 뒤에 판단해도 늦지 않습니다.
개인 키를 로그인 키체인에서 찾지 못하면 인증서를 다시 만들어야 하나요?
먼저 실제 작업 계정과 키체인을 확인하세요. match를 실행한 계정과 Xcode를 실행한 계정이 다르거나, 해당 계정에서 키체인을 사용할 수 없는 상태라면 인증서 재발급이 원인이 아닐 수 있습니다. 비밀값을 로그에 남기지 말고, 조직의 안전한 자산 전달 절차에 따라 키 접근을 복구할 방법을 확인한 뒤 필요한 조치를 선택하세요.
출시용 CI에서 match 읽기 전용 모드를 사용할 수 있나요?
준비된 서명 자산을 가져와 사용하는 출시 빌드라면 읽기 전용 모드를 고려할 수 있습니다. 다만 자산을 생성하거나 문제를 수정하는 기능은 아니므로 저장소 접근과 복호화가 정상인지, 선택된 프로파일이 해당 타깃과 배포 목적에 맞는지 따로 확인해야 합니다. fastlane의 match 문서에서 운영 조건을 점검하세요.
로컬 Archive는 되는데 원격 Archive가 실패하면 무엇을 비교해야 하나요?
실행 계정, 키체인, 자격 증명 공급 방식부터 로컬과 원격 사이에서 비교합니다. 이어서 원격에서 선택된 타깃과 서명 설정, 프로파일, 배포 용도를 확인하세요. Archive 단계와 IPA 내보내기는 서로 다른 단계이므로 실패 위치를 먼저 구분해야 합니다. Apple의 앱 배포 흐름 안내를 참고해 해당 단계의 로그로 원인을 좁히세요.
실제 출시 설정으로 Archive부터 내보내기까지 검증합니다
복구 여부는 인증서 목록이나 Debug 빌드만으로 판정하지 마세요. 실제 프로젝트의 출시용 빌드 구성을 사용해 Archive를 실행하고, 선택된 서명 신원과 프로파일이 의도한 배포 방식에 맞는지 확인합니다. Apple은 앱 배포 과정에서 Archive와 배포 과정의 관계를 안내하므로, Archive 실패와 IPA 내보내기 실패를 각각 해당 단계의 기록으로 구분하세요.
검증 기록에는 작업 계정, 도구 실행 환경, 자격 증명의 공급 경로, 대상 타깃, Archive 결과와 내보내기 결과를 남깁니다. 비밀값이나 개인 키는 기록에서 제외합니다. 이 확인으로 입증되는 것은 해당 프로젝트와 해당 배포 구성의 작업 경로뿐입니다. 다른 프로젝트나 배포 방식까지 검증된 것으로 확대해서는 안 됩니다.
매번 새 맥을 마련하거나 개인 맥을 빌려 쓰는 방식은 구매 비용, 사용 계정과 키체인의 차이, 개발 작업과 출시 작업의 환경 분리 문제를 함께 고려해야 합니다. 반대로 장기간 계속 실행할 고정 작업이 있고 물리 장치나 로컬 주변기기가 필요하다면 직접 보유한 맥이 더 적합할 수 있습니다. 일시적인 이전 검증이나 원격 출시 환경이 필요한 경우에는 실제 macOS 환경을 제공하는 원격 맥 대여가 대안이 됩니다. NodeMini의 원격 맥 이용 안내에서 연결 방식과 이용 조건을 확인하고, 개발 흐름에 맞는지 먼저 판단하세요. 다른 이용 경로와 안내는 NodeMini 한국어 페이지에서 살펴볼 수 있습니다.