fastlane match 인증서 동기화 실패 시 어떻게 해야 할까? 원격 Mac 점검 (2026)

fastlane match 인증서 동기화에 실패하면 원본 로그로 저장소 인증, 복호화, Keychain, 서명 프로파일 중 어디에서 멈췄는지 먼저 구분하세요. 실패한 단계만 복구하고 모든 인증서를 다시 만들거나 취소하지 마세요. 원격 Mac에서는 실제 빌드 작업을 실행하는 사용자와 Keychain 환경까지 확인해야 합니다.

이 안내는 원격 Mac에서 처음 fastlane match를 실행하는 iOS 독립 개발자에게 적합합니다.
빌드 환경을 옮긴 뒤 인증서나 개인 키, 프로파일 오류를 만난 소규모 팀에도 도움이 됩니다.
상시 빌드 환경에서 서명 자료를 중복 발급하거나 실수로 취소하지 않으려는 개발자도 따라 할 수 있습니다.

로그에서 처음 실패한 단계를 찾습니다

처음 실패한 명령과 전체 출력을 저장하세요. 마지막에 표시된 오류만 보고 판단하면 안 됩니다. match 동기화가 끝난 뒤 xcodebuild가 실패한 것이라면 원인은 코드 컴파일이나 프로젝트 서명 설정일 수 있습니다. fastlane의 코드 서명 문제 해결 문서를 참고해 로그의 첫 실패 지점을 기준으로 분류하세요.

• Git 저장소 주소에 접근하지 못하면 저장소 인증이나 권한부터 확인합니다.
• 저장소를 가져온 뒤 복호화에 실패하면 match 저장소 설정과 암호 사용 여부를 살펴봅니다.
• 동기화가 끝났지만 서명 신원 또는 개인 키가 보이지 않으면 인증서 설치와 Keychain을 점검합니다.
• 프로파일 관련 오류가 나면 앱 식별자, target, 서명 유형, 인증서 연결을 확인합니다.
• match가 성공한 다음 빌드에서 실패하면 선택한 Xcode와 프로젝트 서명 설정까지 확인합니다.

로그를 공유하거나 보관할 때 토큰, 저장소 접근 정보, 암호, 개인 키가 포함되지 않도록 가리세요. 조사에 필요한 오류 문맥은 남기되 비밀값 자체를 붙여 넣지는 마세요.

저장소를 가져오지 못하면 인증과 권한부터 확인합니다

원격 Mac에서 Git 저장소를 복제할 수 없다면 암호 해독부터 바꾸지 마세요. 저장소 주소가 현재 match 설정과 일치하는지 확인하고, 빌드 작업이 실행되는 사용자에게 저장소를 읽을 권한이 있는지 점검합니다. SSH를 사용하는 경우 원격 데스크톱에서의 성공만으로 충분하지 않습니다. SSH 또는 자동화 작업이 같은 인증 정보를 실제로 사용할 수 있는지 확인하세요.

복제가 성공한 뒤에야 복호화 문제를 분리할 수 있습니다. fastlane은 match가 저장소에 서명 자료를 보관하고 암호로 보호하는 방식을 설명합니다. match의 저장 방식과 암호 설정 안내에 따라 실제 실행 환경에서 저장소 설정과 복호화 암호를 확인하세요. 로컬 셸에서 설정한 값이 CI 작업이나 다른 사용자 세션에도 전달된다고 가정하면 안 됩니다.

• 저장소 복제 실패: 주소, 접근 권한, SSH 인증 순서로 확인합니다.
• 복제 성공 후 복호화 실패: 실행 환경의 암호와 match 설정을 확인합니다.
• 복제와 복호화가 모두 성공: 인증서 설치 단계로 넘어갑니다.

비밀값을 명령에 직접 입력하거나 로그에 출력하지 마세요. 문제가 해결되지 않으면 값을 노출하지 않는 방식으로 환경 변수와 작업 설정을 대조하고, 수정 전후에 실패 단계가 달라졌는지 확인합니다.

Keychain에 인증서와 개인 키가 함께 있는지 확인합니다

인증서 파일이 있다는 것과 코드 서명이 가능하다는 것은 다릅니다. Apple은 서명 신원에 인증서와 해당 개인 키가 필요하다고 설명합니다. 서명 인증서와 개인 키의 관계를 기준으로, 파일 존재 여부가 아니라 빌드 프로세스가 사용할 수 있는 서명 신원이 등록됐는지 확인하세요.

원격 데스크톱, SSH, CI 작업은 실행 사용자와 로그인 세션이 다를 수 있습니다. 데스크톱에서 인증서를 찾았더라도 자동화 작업에서 같은 Keychain을 볼 수 있다고 단정하지 마세요. fastlane의 일반적인 코드 서명 문제 안내도 인증서와 Keychain 설정을 함께 점검하도록 설명합니다.

점검 결과에 따라 다음 조치를 선택하세요.

• [ ] 원격 데스크톱과 실제 빌드 작업 양쪽에서 서명 신원이 보입니다.
  → Keychain 재설치보다 프로파일과 target 설정을 확인합니다.
• [ ] 원격 데스크톱에서는 보이지만 SSH 또는 CI 작업에서는 보이지 않습니다.
  → 인증서를 새로 만들기 전에 빌드 작업의 실행 사용자와 Keychain 접근을 조정합니다.
• [ ] 인증서는 보이지만 연결된 개인 키가 확인되지 않습니다.
  → match 저장소에 정상적인 서명 자료가 있는지 확인하고, 필요한 자료를 다시 동기화합니다.
• [ ] 위 항목을 확인하지 못했거나 로그가 다른 단계의 실패를 가리킵니다.
  → 인증서를 취소하거나 프로파일을 재생성하지 말고, 원본 로그에서 첫 실패 지점부터 다시 분류합니다.

Keychain을 수정할 때는 실제 빌드를 실행하는 사용자로 재현하세요. 관리자 세션에서 확인한 결과를 일반 사용자나 CI 작업의 상태로 간주하면 원인을 놓칠 수 있습니다.

Provisioning Profile은 target별로 대조합니다

인증서가 설치되어 있어도 Provisioning Profile이 프로젝트 설정과 맞지 않으면 서명이 실패합니다. 실패한 target의 Bundle ID와 프로파일의 앱 식별자, 서명 유형, 연결된 인증서를 각각 비교하세요. 메인 앱의 설정이 맞는다고 해서 별도 확장 target도 맞는 것은 아닙니다.

Apple의 프로파일 편집 및 다운로드 안내와 App Store용 프로파일 생성 절차에서 프로파일 내용을 확인하고 관리하는 기준을 살펴볼 수 있습니다. 프로젝트의 실제 설정과 프로파일 내용을 먼저 대조한 다음 필요할 때만 업데이트하거나 다시 생성하세요.

• 프로젝트의 Bundle ID가 프로파일의 앱 식별자와 일치하는지 확인합니다.
• 실패한 target이 사용하는 프로파일과 서명 유형이 의도한 배포 방식에 맞는지 확인합니다.
• 프로파일에 포함된 인증서가 Keychain에서 사용할 수 있는 인증서와 연결되는지 확인합니다.
• 자동 서명과 수동 서명 설정이 섞여 있지 않은지 target별로 살펴봅니다.

무조건 강제 새로고침하거나 프로파일을 다시 만들면 원래 설정 문제를 가린 채 변경 범위만 넓힐 수 있습니다. 기존 프로파일의 실제 내용을 확인하고 불일치가 확인된 항목만 수정하세요.

선택된 Xcode와 명령 실행 환경을 확인합니다

같은 저장소와 서명 자료를 사용해도 fastlane 작업과 빌드가 서로 다른 Xcode를 참조하면 결과가 달라질 수 있습니다. 문제가 난 작업의 셸에서 xcode-select -p를 실행해 선택된 개발자 도구 경로를 확인하고, fastlane 실행 환경과 빌드 환경이 같은 Xcode를 사용하는지 비교하세요. 명령줄 도구 선택은 Xcode 명령줄 도구 참고 문서를 기준으로 확인할 수 있습니다.

여러 target을 가진 프로젝트라면 설정을 한꺼번에 추정하지 마세요. 실패한 target마다 Bundle ID, 프로파일 지정, 서명 방식이 무엇인지 확인합니다. 기본 앱에서 빌드가 성공해도 다른 target의 설정까지 정상이라는 뜻은 아닙니다. 마지막으로 fastlane의 성공 결과와 최종 아카이브의 서명 결과를 각각 확인해야 합니다.

수정 후 같은 실행 방식으로 다시 검증합니다

원인을 고친 뒤에는 다음 순서로 검증하면 재발 원인을 좁히기 쉽습니다.

1. 문제가 난 사용자와 작업 방식 그대로 fastlane match를 다시 실행합니다. 자동화 작업에서 발생했다면 SSH나 CI 환경에서 검증하고, 개인 데스크톱 세션의 성공만으로 완료 처리하지 않습니다.
2. 동기화 로그에서 저장소 접근, 복호화, 설치가 각각 통과했는지 확인합니다. 원본 실패와 비교해 실제로 어느 단계가 바뀌었는지 기록합니다.
3. 빌드를 실행하는 같은 사용자와 Keychain 환경에서 사용할 서명 신원과 개인 키를 확인합니다.
4. 실패한 target의 Bundle ID, Provisioning Profile 내용, 서명 설정을 대조합니다. 빌드에 포함된 관련 target도 확인합니다.
5. 문제가 발생했던 빌드 명령으로 다시 빌드하고, 최종 아카이브에서 의도한 앱과 서명 설정이 적용됐는지 확인합니다.

재검증 기록에는 실행 방식, 작업 사용자, 선택된 Xcode, 실패 target, 수정한 설정과 확인 결과를 남기세요. 비밀값이나 개인 키는 기록하지 않습니다. 이 기록이 있으면 다음 환경 이전 때 저장소 접근 문제와 서명 설정 문제를 구별하기 쉽습니다.

자주 묻는 문제를 추가로 점검합니다

새 원격 Mac에서 복제는 되지만 복호화에 실패하는 경우

먼저 fastlane match가 실제로 실행되는 셸이나 작업 환경에 복호화 암호가 제공되는지 확인합니다. 로컬 Mac의 환경 설정이 원격 Mac에 자동으로 공유되지는 않습니다. 저장소 암호를 로그나 명령줄에 직접 적지 말고, 실행 환경의 비밀값 설정과 match 저장소 구성이 맞는지 확인하세요. 기존 저장소 설정을 검증하기 전에 자료를 새로 만들면 원인 분석이 어려워집니다.

인증서 파일은 있는데 원격 Mac이 개인 키를 찾지 못하는 경우

인증서 파일의 존재만으로 개인 키까지 Keychain에 들어갔다고 볼 수 없습니다. 빌드 작업과 같은 사용자 및 세션에서 서명 신원을 확인하고, 데스크톱 세션과 SSH 또는 자동화 작업의 Keychain 접근을 비교하세요. 일치하지 않으면 실행 사용자와 Keychain 환경을 먼저 조정합니다. 인증서를 새로 발급하기 전에는 match 저장소에 정상적인 인증서와 개인 키가 함께 보관되어 있는지 확인하세요.

프로파일 불일치 오류가 나면 어떤 항목을 먼저 비교하나요?

오류가 난 target의 Bundle ID와 프로파일의 앱 식별자를 대조합니다. 이어서 서명 유형과 프로파일에 포함된 인증서가 빌드 설정과 맞는지 확인하세요. 여러 target이 있다면 각각 별도로 검사해야 합니다. 불일치가 확인된 경우에만 프로젝트 설정을 고치거나 프로파일을 갱신 또는 재생성합니다. 모든 프로파일을 무조건 다시 받는 방식은 우선 선택하지 마세요.

SSH나 CI에서만 Keychain 접근에 실패하는 경우

성공한 데스크톱 세션과 실패한 작업의 실행 사용자가 같은지부터 살펴봅니다. 다음으로 해당 작업이 접근하는 Keychain과 인증서 설치 상태를 확인합니다. SSH나 CI의 조건이 데스크톱 로그인 세션과 다를 수 있으므로 한쪽에서 성공한 결과를 다른 쪽의 증거로 사용하면 안 됩니다. 작업이 실행되는 방식 그대로 서명 신원과 프로파일을 재검증하고 해당 환경에 맞게 접근 설정을 정리하세요.

원격 빌드 환경이 필요한지 운영 조건으로 결정합니다

로컬 빌드는 정상인데 원격에서 서명이 반복해서 흔들린다면 저장소 접근, 복호화, Keychain 세션, target별 프로파일을 나눠 확인하세요. 로컬 Mac은 이미 익숙한 로그인 환경을 그대로 쓸 수 있지만, 별도 빌드 장비를 직접 운영하면 초기 설정과 지속적인 관리가 필요합니다. 공유형 클라우드 빌드는 실행 환경 통제와 Keychain 접근이 요구에 맞는지 먼저 검토해야 합니다.

출시가 간헐적이고 원격 환경을 계속 유지할 필요가 없다면 로컬 Mac에서 빌드하는 편이 간단할 수 있습니다. 반대로 서명 설정을 고정한 Mac이 필요하고 원격 실행을 반복한다면 MangoVM의 원격 Mac을 검토할 수 있습니다. 환경 이전 뒤의 검증 기준은 MangoVM 도움말에서 확인하고, 비밀값을 다루는 방식은 데이터 보호 안내에서 살펴보세요. 자신의 배포 주기와 운영 부담에 맞춰 원격 빌드 환경이 필요한지 결정하면 됩니다.

자주 묻는 질문