fastlane match 서명 실패: 2026 원격 Mac 점검 목록

fastlane match 서명 실패가 발생했다면 먼저 match nuke나 인증서 재생성부터 실행하지 말고, 저장소 접근과 복호화, Keychain의 완전한 서명 신원, Provisioning Profile 매핑, CI 설정을 차례로 확인해야 합니다. 이 순서는 원격 Mac에서 Archive가 실패하지만 로컬에서는 성공하는 독립 개발자와 소규모 팀에 적합합니다.

이번 주에는 실패 로그를 가린 뒤 보관하고, 같은 커밋과 같은 Archive 명령으로 원격 환경을 다시 실행하세요. 인증서가 실제로 만료되었거나 복구할 수 없다는 증거가 있을 때만 교체 단계로 넘어가면 됩니다.

fastlane match 서명 실패 판단 기준

서명 실패는 한 가지 문제가 아닙니다. 다음 네 층 가운데 어디에서 멈췄는지 먼저 나누면 불필요한 인증서 폐기를 피할 수 있습니다.

• 자산 취득 단계: fastlane match가 저장소에 접근하지 못했거나 암호화된 자산을 풀지 못한 경우입니다.
• 설치 단계: 인증서 파일은 내려받았지만 개인 키가 Keychain에 없거나, 빌드 사용자가 해당 Keychain을 읽지 못하는 경우입니다.
• 선택 단계: 인증서와 프로파일은 존재하지만 Target, Bundle ID 또는 entitlements와 연결되지 않은 경우입니다.
• 검증 단계: Archive 또는 내보내기 뒤에 서명 검증, 배포 대상, 업로드 권한에서 실패하는 경우입니다.

Apple은 서명에 사용하는 인증서와 개인 키의 관계를 구분하며, Provisioning Profile에는 앱 식별자와 권한 정보가 포함됩니다. 따라서 로그에 No signing certificate가 보인다는 이유만으로 인증서가 사라졌다고 단정하면 안 됩니다. Apple의 코드 서명과 프로파일 구조 설명을 기준으로 자산을 분리해 보세요.

먼저 남길 증거

다음 자료를 비밀번호와 식별 정보가 보이지 않도록 가린 뒤 저장합니다.

• fastlane match가 실패한 전체 구간과 프로세스 종료 상태
• 사용한 lane, Scheme, Configuration, export 옵션
• 활성 Xcode 확인 결과와 빌드 사용자의 계정
• MATCH_PASSWORD, 저장소 주소, 브랜치, Team ID, Bundle ID의 적용 여부
• Keychain 조회 결과와 설치된 서명 신원의 이름
• 현재 Target의 Code Signing 설정과 entitlements

토큰, 배포 키, 저장소 암호, Keychain 이름, 실제 경로는 로그에 그대로 남기지 마세요. fastlane의 공식 서명 문제 해결 문서도 저장소, 인증서, 프로파일, 빌드 설정을 분리해 확인하는 흐름을 제시합니다. fastlane 서명 문제 해결 안내도 함께 대조하면 됩니다.

저장소 접근과 복호화 문제

fastlane match가 서명 인증서를 찾지 못할 때는 무엇부터 확인해야 합니까?

소스 저장소를 내려받을 수 있다고 서명 저장소까지 접근할 수 있는 것은 아닙니다. 두 저장소가 다른 주소, 다른 브랜치, 다른 배포 키를 사용할 수 있기 때문입니다. Git 저장소를 쓰는지 객체 저장소를 쓰는지부터 확인하고, CI에서 사용하는 자격 증명으로 별도 읽기 테스트를 실행해야 합니다.

다음 항목을 한 번에 바꾸지 말고 하나씩 기록하세요.

• 저장소 주소가 기대한 값인지 확인합니다.
• 브랜치 또는 저장 영역 이름이 팀 설정과 일치하는지 확인합니다.
• CI 비밀 변수에 저장소 접근 키와 복호화 암호가 모두 등록되어 있는지 확인합니다.
• MATCH_PASSWORD가 기존 저장소를 만들 때 사용한 값과 같은지 검증합니다.
• 읽기 권한만 있는 키로 쓰기 작업을 시도하고 있지 않은지 확인합니다.

readonly는 이미 존재하는 자산을 읽고 설치하는 운영 방식입니다. 관리자가 새 인증서나 프로파일을 만들어 주는 기능을 대신하지 않습니다. match 공식 문서의 저장 방식과 readonly 설명에 따라 CI에서는 읽기 자격 증명과 자산 생성 권한을 분리하세요.

주의: 로그에 실제 저장소 주소, Team ID, 토큰, 복호화 암호를 넣지 마세요. 문제 재현용 명령은 <저장소_주소>, <브랜치>, <복호화_암호>처럼 명확한 자리표시자로 작성해야 합니다.

인증서 파일과 Keychain의 차이

인증서 파일이 내려받아졌다는 사실만으로 빌드 가능한 서명 신원이 완성되는 것은 아닙니다. 실제 서명에는 인증서와 대응하는 개인 키가 함께 필요합니다. 개인 키가 다른 Keychain에 있거나, 원격 작업 사용자가 잠긴 Keychain에 접근하지 못하면 Archive는 실패합니다.

원격 Mac을 재시작한 뒤 Keychain을 열 수 없을 때는 어떻게 복구합니까?

먼저 빌드 프로세스가 어느 Keychain을 보고 있는지 확인합니다. 그 다음 해당 Keychain이 잠겨 있는지, 원격 세션이 끝난 뒤에도 잠금 해제 상태가 유지되는지, CI 사용자가 접근할 수 있는지 차례로 확인합니다. 무조건 모든 Keychain 권한을 허용하거나 계속 대화형 로그인에 의존하는 방식은 기본 해결책으로 삼지 않는 편이 안전합니다.

진단 순서는 다음과 같습니다.

1. security find-identity로 코드 서명에 사용할 수 있는 신원을 조회합니다.
2. 인증서 이름만 있고 대응하는 개인 키가 없는지 확인합니다.
3. match가 자산을 설치한 Keychain과 Archive를 실행하는 사용자의 Keychain이 같은지 비교합니다.
4. 원격 Mac을 재시작한 뒤 같은 조회를 반복합니다.
5. 잠금 해제 과정과 접근 권한을 최소 범위로 다시 설정합니다.

Apple의 배포 안내에서도 등록 기기, 인증서, 프로파일을 서로 다른 구성 요소로 다룹니다. Apple의 앱 배포용 서명 안내를 참고해 인증서 파일만 복사하는 방식과 실제 서명 신원 설치를 구분하세요.

Provisioning Profile과 Target 매핑

Provisioning Profile은 파일이 존재하는지만 확인해서는 부족합니다. 현재 Target의 Bundle ID, Team, 프로파일 유형, 연결된 인증서, entitlements가 모두 맞아야 합니다.

match readonly에서 Provisioning Profile을 찾지 못하면 어떻게 해야 합니까?

먼저 해당 프로파일이 저장소에 없는지, 만료 또는 폐기된 것인지, 현재 Target이 다른 이름의 프로파일을 선택하는지 나눠야 합니다. readonly 상태에서는 누락된 자산을 새로 만들지 않으므로, 관리자 권한이 필요한 생성 또는 갱신 작업을 별도 실행해야 합니다.

다중 Target에서는 다음 매핑을 목록으로 만들어 보세요.

• 기본 앱의 Bundle ID와 프로파일
• 위젯 또는 알림 확장의 Bundle ID와 프로파일
• macOS 앱과 보조 도구의 Bundle ID와 프로파일
• 각 Target이 요구하는 entitlements
• 각 프로파일에 연결된 Apple Distribution 인증서

여러 Bundle ID는 fastlane match에서 어떻게 관리해야 합니까?

하나의 저장소를 공유하더라도 Bundle ID별 자산을 명확한 이름과 역할로 관리해야 합니다. 기본 앱과 확장 구성 요소를 한 프로파일로 처리하려고 하면 Xcode가 다른 프로파일을 선택하거나 특정 entitlement가 빠질 수 있습니다. Apple의 프로파일 관리 문서에서 현재 앱 식별자와 프로파일 상태를 확인한 뒤, Target별 매핑을 다시 작성하세요.

Xcode와 fastlane의 버전에 따라 설치 위치나 선택 동작이 달라질 수 있습니다. 특정 경로가 항상 같다고 가정하지 말고, 실제 설치 결과와 프로젝트의 서명 설정을 함께 확인해야 합니다.

로컬 성공과 원격 Archive의 차이

로컬 Xcode가 자동 서명을 사용하면 개발자 계정에 있는 자산을 바탕으로 설정을 보완할 수 있습니다. 반면 원격 CI는 명시된 Scheme, Configuration, export 옵션과 빌드 사용자의 권한만 사용합니다. 그래서 로컬 성공은 원격 환경의 서명 체인이 완전하다는 증거가 아닙니다.

원격 실행에서는 다음 순서를 고정하세요.

• 올바른 Xcode를 선택합니다.
• 같은 커밋을 가져옵니다.
• match를 Archive보다 먼저 실행합니다.
• CI에서는 의도한 readonly 정책을 적용합니다.
• 같은 Scheme과 Configuration으로 Archive합니다.
• 같은 내보내기 대상과 옵션으로 결과를 검증합니다.

fastlane은 CI에서 비밀 값과 서명 자산을 안전하게 주입하는 구성을 별도로 설명합니다. fastlane 지속적 통합 설정 안내를 기준으로 소스 저장소 자격 증명과 서명 저장소 자격 증명을 분리하세요.

복구 선택표

수정과 교체의 경계

인증 방식이나 매핑만 잘못된 경우에는 기존 자산을 유지한 채 원인을 수정합니다. 인증서 만료, 권한 변경, 프로파일 폐기처럼 상태가 바뀐 경우에는 영향받는 자산만 통제된 방식으로 교체합니다. 저장소 자산을 복구할 수 없고 영향 범위까지 확인된 경우에만 재구축을 검토합니다.

match nuke는 관련 인증서와 프로파일을 정리하는 고위험 작업입니다. match nuke 공식 문서를 확인하고 실행 전 앱, 배포 방식, 인증서, 프로파일, 진행 중인 출시 작업의 관계를 기록하세요. 운영 중인 다른 앱의 배포까지 막을 수 있으므로 긴급한 로그 한 줄만 보고 실행해서는 안 됩니다.

복구가 끝났다고 판단하려면 비긴급 브랜치에서 다음을 확인합니다.

• 같은 커밋으로 match가 완료됩니다.
• 원격 Mac을 재시작한 뒤 Keychain과 개인 키를 다시 읽습니다.
• Archive가 성공합니다.
• export 결과의 서명과 entitlements를 검증합니다.
• 실제 업로드 전 단계에서 배포 자산과 앱 식별자가 일치하는지 확인합니다.

손으로 관리하던 인증서를 원격 환경으로 옮기는 중이라면 iOS 개발 인증서 이전 점검 안내에서 원격 작업 환경의 유지 조건도 함께 확인할 수 있습니다. 장시간 켜 두어야 하는 빌드 머신이 필요하다면 원격 Mac 이용 방식을 비교하되, 먼저 재시작 후 Archive 검증을 기준으로 적합성을 판단하세요.

임시 CI 머신은 Keychain이 초기화되거나 작업이 중단될 때마다 같은 장애를 반복할 수 있습니다. 반대로 직접 보유한 Mac은 물리 장치와 초기 구매 비용을 관리해야 하고, 짧은 테스트에는 과한 자원이 될 수 있습니다. 현재 환경에서 저장소 자격 증명, Keychain 지속성, 원격 재시작 복구를 통제하기 어렵다면 VMSPIN의 원격 Mac에서 비긴급 출시 브랜치로 서명 체인을 재현해 보는 편이 현실적인 선택입니다. 재시작 뒤에도 Archive와 내보내기가 끝나는지 확인한 뒤, 장기 사용 여부를 결정하면 됩니다.