fastlane match 비공개 저장소 가져오기 실패 시 어떻게 할까? 2026 원격 맥 점검

저장소를 가져오지 못하거나, 가져온 뒤 서명이 막힙니다.
먼저 Git 접근, match 암호, Apple 계정, 서명 신원을 구분해 확인하세요. CI와 무인 빌드는 읽기 전용으로 운영하고, 원인을 모른 채 인증서를 다시 만들거나 폐기하지 마세요.

이 글은 fastlane match를 원격 맥에 처음 연결했거나 서명 자료를 읽지 못하는 독립 개발자를 위한 안내입니다.
공유 서명 저장소의 쓰기 권한을 정리해야 하는 팀 책임자도 참고할 수 있습니다.
새 맥이나 CI로 옮긴 뒤 빌드가 멈춘 배포 담당자에게도 해당합니다.

먼저 구분할 오류 층위

fastlane match의 실패를 전부 “인증 오류”로 묶으면 엉뚱한 비밀번호를 바꾸거나 서명 자산을 재발급하게 됩니다. 다음 항목은 서로 다른 자격 증명과 구성에 해당합니다.

• Git 인증: 저장소에 연결하고 필요한 참조를 읽을 권한입니다. SSH 키나 HTTPS 자격 증명이 여기에 해당합니다.
• match 암호: 저장소 안의 암호화된 서명 자료를 해독할 때 사용합니다. 저장소 접근 권한과는 별개입니다.
• Apple 계정 확인: 개발자 계정에 접근하거나 관련 작업을 수행하는 단계의 문제입니다. 저장소 읽기 실패와 구분해야 합니다.
• 서명 신원: 인증서와 대응하는 개인 키, 대상에 맞는 프로비저닝 프로파일이 갖춰져야 합니다. 자료를 내려받았다는 사실만으로 유효한 서명이 보장되지는 않습니다.

우선 오류 메시지와 실행 환경을 기록하세요. 저장소 주소, 계정 이름, 호스트 주소, 토큰, 인증서 식별자, 파일 경로와 로그에 포함된 비밀 값은 공유 전에 가려야 합니다.

주의: 비밀번호나 토큰을 명령 기록, 저장소 파일, 공개 가능한 빌드 로그에 넣지 마세요. 로그 전체를 복사하는 대신 오류 유형과 민감한 값을 지운 일부만 남기세요.

환경별 저장소 접근 확인

개발자 본인 맥에서는 되지만 새 원격 맥에서 실패한다면 저장소 자체보다 그 원격 맥에서 실제로 어떤 계정과 키를 사용하는지부터 확인합니다. 로그인한 사용자와 빌드 프로세스가 실행되는 사용자가 다를 수 있습니다. 터미널에서 확인한 SSH 키가 자동 실행 작업에도 적용된다고 가정하지 마세요.

저장소가 Git 기반이라면 git ls-remote로 원격 저장소에서 참조 목록을 읽을 수 있는지 확인할 수 있습니다. 이 명령은 원격 저장소의 보이는 참조를 표시합니다. 파일을 복호화하거나 Xcode 서명 상태까지 검증하는 명령은 아닙니다. git ls-remote 문서

SSH 연결을 쓰는 경우에는 실행 사용자와 사용 키를 확인한 다음 SSH 연결 시험을 진행하세요. 공식 연결 시험 안내의 결과와 fastlane 오류를 함께 비교하면, 연결 단계에서 거부되는지 match 실행 중 실패하는지 좁힐 수 있습니다. SSH 연결 시험 안내

저장소가 배포 키를 쓰는 팀이라면 해당 키가 의도한 저장소에만 연결됐는지 확인하세요. 개인 계정 비밀번호를 팀원과 공유하거나 저장소를 공개로 바꿔 우회하지 마세요. 배포 키의 적용 범위와 관리 방법

실행 환경	먼저 확인할 항목	읽기 권한 확인 뒤 볼 항목
개발자 본인 맥	현재 사용자, SSH 키 또는 HTTPS 자격 증명	match 암호, 키체인과 서명 상태
새 원격 맥	빌드 실행 사용자, 저장소 인증 방식	해당 사용자 환경의 암호 주입과 키체인
GitHub Actions	작업에 비밀 값이 전달되는 범위, 저장소 권한	읽기 전용 설정, 프로파일과 서명 신원

원격 맥에서 저장소를 가져오지 못하면 무엇부터 보나요? git ls-remote 결과와 SSH 연결 결과를 살펴보세요. 참조를 읽지 못하면 Git 인증이나 저장소 권한부터 점검합니다. 참조를 읽을 수 있다면 저장소 주소가 match 설정과 일치하는지 확인한 뒤, 암호 해독과 서명 단계로 넘어가세요.

HTTPS를 사용하는 경우에는 원격 맥의 자격 증명 저장 방식도 확인해야 합니다. 개발자 맥에만 저장된 토큰은 새 환경에서 자동으로 제공되지 않습니다. 원격 저장소에서 사용하는 저장 방식이 Git 이외의 서비스라면, 그 서비스의 인증 정보와 접근 범위도 별도로 확인하세요.

저장소를 읽지만 암호 해독이 실패하는 경우

저장소 참조를 읽을 수 있는데 암호화된 파일을 열지 못한다면 Git 인증을 반복해서 바꾸기보다 match 암호가 해당 실행 환경에 전달되는지 확인하세요. 변수 이름이 프로젝트 설정과 일치하는지, 비밀 값이 실제 빌드 작업에 노출되는 범위에 포함되는지도 살펴봅니다.

GitHub Actions에서는 비밀 값의 이용 범위가 저장소 및 작업 구성에 따라 달라질 수 있습니다. 작업을 실행하는 주체와 비밀 전달 조건을 확인하고, 빌드 출력에 값을 찍어 검증하지 마세요. Actions 비밀 값의 사용 범위와 제한

원격 맥에서 암호 오류와 Git 인증 실패를 어떻게 나누나요? 원격 참조를 읽는 단계부터 실패한다면 Git 인증을 먼저 조사합니다. 참조 읽기가 성공한 뒤 암호화된 자료를 해독하지 못한다면 match 암호가 의심 대상입니다. 둘을 같은 자격 증명으로 취급하지 마세요.

개발자 맥에서는 로그인 키체인이나 셸 설정을 통해 암호가 제공되지만, CI에서는 비밀 저장소에서 작업 환경으로 전달해야 할 수 있습니다. 어느 환경에서 어떤 방식으로 주입하는지 문서화하세요. 암호를 저장소에 커밋하거나 명령줄 인수로 직접 노출하는 방식은 피해야 합니다.

팀 저장소의 읽기와 쓰기 경계

공유 저장소는 모든 개발자와 자동화 작업에 쓰기 권한을 줄 필요가 없습니다. 역할에 맞게 권한을 나누세요.

• 개발자: 빌드에 필요한 자료를 읽을 수 있는지 확인합니다. 불필요한 갱신 권한은 주지 않습니다.
• 저장소 관리자: 접근 주체를 관리하고, 키나 토큰이 교체될 때 적용 범위를 점검합니다.
• CI 유지 담당자: 작업에 필요한 비밀 값만 전달하고, 빌드 결과에 서명 자료나 비밀이 출력되지 않는지 확인합니다.
• 승인된 서명 자산 관리자: 팀 절차에 따라 새 자료를 생성하거나 저장소를 갱신합니다.

CI에서 fastlane match를 실행할 때 읽기 전용이어야 하나요? 서명 자료를 가져와 빌드하는 CI라면 readonly 설정을 우선 검토하세요. fastlane 공식 문서는 CI 사용에서 읽기 전용 모드를 권장합니다. 저장소를 갱신하는 작업은 승인된 유지 담당자가 팀 절차에 따라 별도로 수행하세요. match의 저장 방식과 CI 읽기 전용 설정

이 방식은 자동 작업이 공유 자산을 뜻하지 않게 바꾸는 위험을 줄입니다. 반면 서명 자료의 생성이나 갱신이 필요한 상황에서는 읽기 전용 작업만으로 해결되지 않습니다. 그때는 권한을 넓히기 전에 누가 어떤 변경을 승인하는지부터 정해야 합니다.

자료를 가져온 뒤 서명이 실패하는 경우

match가 저장소에서 자료를 가져왔더라도 Xcode가 쓸 수 있는 서명 신원이 준비됐는지 확인해야 합니다. Apple은 코드 서명 인증서와 그에 대응하는 개인 키를 서명 신원의 구성 요소로 설명합니다. 인증서만 키체인에 있고 개인 키가 없다면 서명 단계에서 막힐 수 있습니다. 코드 서명 인증서와 개인 키 설명

그다음 프로비저닝 프로파일이 빌드 대상과 맞는지 살펴보세요. 앱 식별자나 필요한 기능이 대상과 맞지 않으면 자료가 있어도 서명이나 설치 과정에서 거부될 수 있습니다. 프로파일의 조건과 연결 관계는 Apple의 설명을 기준으로 확인합니다. 프로비저닝 프로파일의 구성과 조건

match가 성공했는데 Xcode가 인증서를 찾지 못하면 어떻게 하나요? 현재 빌드 사용자의 키체인에서 인증서와 대응 개인 키가 함께 있는지 확인하고, 빌드 대상에 맞는 프로파일인지 따로 점검하세요. Apple 계정 확인 실패와 로컬 서명 자산 누락은 다른 문제입니다. 하나의 오류로 보고 인증서를 바로 다시 만들지 마세요.

프로파일을 갱신하거나 내려받아야 하는 경우에는 기존 프로파일에 영향을 주는 작업인지 먼저 확인하세요. Apple은 프로파일의 편집, 내려받기, 삭제 절차를 안내합니다. 프로비저닝 프로파일 관리 절차

키체인 정리, 인증서 교체 또는 폐기 전에 해당 인증서를 사용하는 다른 앱과 빌드 작업을 확인하세요. 영향 범위와 복구에 쓸 이전 자료를 확인하지 못했다면 변경을 보류하는 편이 안전합니다.

복구 경로 선택과 빌드 검증

다음 조건에 맞춰 점검 경로를 고르세요.

• 원격 참조 목록을 읽을 수 없다면 Git 인증, 저장소 주소, 실행 사용자 권한을 먼저 고치세요. 암호나 인증서를 바꾸는 단계로 건너뛰지 마세요.
• 참조는 읽히지만 자료 해독이 실패한다면 match 암호의 변수 이름과 환경별 주입 범위를 확인하세요. Git 키를 교체하는 대신 비밀 값 전달을 수정하세요.
• 자료 해독까지 끝났지만 서명이 실패한다면 키체인의 인증서와 개인 키, 프로파일 조건을 확인하세요. 저장소 접근 설정을 반복해서 변경하지 마세요.
• Apple 계정 확인 단계에서만 실패한다면 계정 권한이나 인증 흐름을 별도로 점검하세요. 로컬 키체인의 인증서 재발급으로 계정 문제를 해결하려 하지 마세요.
• CI가 서명 자료를 가져와 빌드하는 용도라면 readonly를 사용하세요. 쓰기가 필요한 작업은 권한 있는 유지 담당자의 절차로 분리하세요.

수정 뒤에는 저장소 접근 성공만으로 완료 처리하지 마세요. 아래 순서대로 증거를 남기면 실패 지점을 추적하기 쉽습니다.

• 빌드와 같은 사용자 및 실행 환경에서 저장소 참조를 읽을 수 있는지 확인합니다.
• 비밀 값이 로그에 출력되지 않는 상태로 match가 자료를 해독하고 가져오는지 확인합니다.
• 빌드 사용자의 키체인에서 인증서와 대응 개인 키를 확인합니다.
• 프로파일이 대상 앱 식별자와 필요한 기능에 맞는지 검토합니다.
• 실제 프로젝트 빌드와 Archive까지 실행하고, 각 단계의 성공 결과를 별도로 기록합니다.

이 과정을 통과하면 저장소 접근 복구와 실제 서명 빌드 검증을 구분할 수 있습니다. 특히 CI에서는 읽기 권한, 비밀 값 전달, 서명 결과를 각각 기록해야 다음 환경 이전 때 같은 고장을 빠르게 찾을 수 있습니다.

원격 빌드 환경을 선택할 때

현재 개발자 맥만 쓰면 저장 공간이나 장비 접근이 병목이 될 수 있고, 직접 운영하는 CI는 자격 증명 전달과 키체인 유지 책임이 남습니다. 일반 클라우드 빌드만으로는 로컬 Xcode 환경에서 확인해야 할 서명 동작을 똑같이 재현하지 못하는 경우도 있습니다. 먼저 문제가 저장소 권한인지, 지속적으로 쓸 macOS 빌드 환경이 없는 것인지 구분하세요.

근본 원인이 서명 빌드에 쓸 맥 환경의 부재라면 MACCOME의 맥 환경 안내와 맥 미니 이용 정보를 비교해 보세요. 가끔 테스트하는 개발자는 기존 장비나 필요할 때 쓰는 환경이 더 나을 수 있습니다. 빌드를 자주 수행하고 상시 실행할 맥이 필요하다면 MACCOME 원격 맥 대여를 검토할 수 있습니다. 다만 물리 포트가 필요한 작업이나 장기간 지속되는 고부하 작업은 원격 대여가 맞지 않을 수 있으므로, 사용 빈도와 작업 조건을 기준으로 결정하세요.