Xcode Cloud 비공개 의존성 가져오기 실패, 2026 점검 가이드

Apple은 Xcode Cloud 사용자 스크립트의 실행 시점을 post-clone, pre-xcodebuild, post-xcodebuild의 세 단계로 안내합니다. 사용자 빌드 스크립트 문서

증상 → 가장 빠른 조치: 비공개 의존성을 가져오지 못했다면 먼저 빌드 보고서에서 실패가 저장소 접근, 의존성 해석, 스크립트 가운데 어디서 발생했는지 확인하세요. 해당 단계에 맞춰 권한이나 설정을 검증하면 됩니다. 비공개 의존성이 있다는 사실만으로 Xcode Cloud를 포기할 필요는 없습니다.

이 글은 Xcode Cloud 워크플로를 관리하며 저장소 접근 오류를 조사하는 엔지니어를 위한 안내입니다.
기업 Swift Package, Git 하위 모듈, 여러 저장소에 걸친 의존성을 관리하는 팀 책임자도 확인할 수 있습니다.
기업 네트워크나 도구 요구가 현재 실행 환경에서 충족되는지 판단해야 하는 IT 담당자와 기술 책임자에게도 유용합니다.

Xcode Cloud 비공개 의존성 가져오기 실패는 단계 구분부터

실패 메시지만 보고 원인을 확정하지 마세요. 저장소 복제, 의존성 해석, 사용자 스크립트, Xcode 빌드 중 어느 단계에서 오류가 났는지 빌드 보고서로 먼저 좁힙니다. Apple도 Xcode Cloud가 비공개 의존성이나 필요한 도구에 접근할 수 없으면 빌드가 실패할 수 있다고 설명하지만, 개별 프로젝트의 원인은 로그와 재현으로 확인해야 합니다. 의존성 접근과 준비에 관한 Apple 안내

관찰되는 증상	우선 조사할 지점	첫 확인 항목
저장소를 복제하거나 하위 모듈을 가져오는 중 실패	저장소 연결 및 접근 승인	실패한 저장소의 실제 주소와 연결 상태
Swift Package 확인 중 실패	패키지 저장소 접근 및 잠금 상태	Package.resolved의 위치와 커밋 여부
도구 설치나 의존성 준비 단계에서 실패	패키지 관리자 또는 준비 스크립트	설치 명령, 잠금 파일, 명령 종료 상태
사용자 스크립트 실행에서 실패	스크립트 경로, 실행 시점, 환경 변수	빌드 보고서의 단계와 스크립트 출력
의존성 준비 후 Xcode 빌드에서 실패	프로젝트 빌드 설정과 실제 해석 결과	실패 단계가 의존성 접근인지 컴파일인지 구분

이 표의 우선순위는 원인을 확정하는 점수가 아니라 조사 순서를 정하는 기준입니다. 같은 오류 문구라도 접근 권한, 경로, 도구 준비가 서로 다른 원인일 수 있습니다.

저장소 연결을 바꾼 뒤에는 실패한 빌드의 로그와 새 빌드의 로그를 함께 비교하세요. 단순히 같은 오류가 사라졌는지만 보지 말고, 실패 단계가 이동했는지도 확인해야 다음 원인을 놓치지 않습니다.

저장소 승인과 여러 인스턴스 연결 확인

비공개 Swift Package, Git 하위 모듈, 스크립트에서 가져오는 코드가 각각 어디에 저장돼 있는지 적어 두세요. Xcode Cloud에 연결된 주 저장소만 확인하고 의존성 저장소의 연결을 놓치면, 앱 저장소는 복제돼도 의존성 가져오기에서 멈출 수 있습니다. Apple의 코드 저장소 연결 설명과 실패 빌드 보고서의 안내를 함께 확인하세요.

의존성 위치	연결 확인 방법	주의할 점
주 앱 저장소와 같은 인스턴스	해당 저장소 연결과 빌드 접근 상태를 확인	앱 저장소 승인이 모든 다른 저장소까지 보장한다고 가정하지 않기
같은 코드 호스팅 서비스의 다른 인스턴스	실제 인스턴스와 저장소 주소를 확인하고 추가 접근 안내 점검	서비스 이름이 같아도 인스턴스가 다를 수 있음
별도의 코드 호스팅 서비스	의존성 저장소가 있는 서비스의 연결 상태를 따로 확인	주 저장소와 의존성 저장소의 접근 경로를 혼동하지 않기
비공개 Git 하위 모듈	하위 모듈 주소와 저장소 접근 요구를 확인	상위 저장소를 읽을 수 있어도 하위 저장소 접근이 별도로 필요할 수 있음

새로운 비공개 의존성을 추가했다면 해당 의존성을 사용하는 빌드 보고서에 접근 승인 안내가 있는지 보세요. 여러 인스턴스가 연결돼 있다면 앱 코드와 의존성 코드가 각각 어느 인스턴스에 있는지 대조합니다. 초기 연결에 성공했다는 사실만으로 모든 저장소가 승인됐다고 판단하지 말고, 실제 빌드가 요구하는 저장소를 확인해야 합니다. Xcode Cloud 워크플로 설정 안내도 연결 상태를 점검할 때 참고할 수 있습니다.

Package.resolved와 도구 준비 상태 확인

Swift Package의 해석 오류라면 Package.resolved가 저장소에 포함돼 있는지, 예상한 프로젝트 경로에 있는지, 현재 빌드가 사용하는 브랜치의 커밋에 들어 있는지 확인하세요. 개발자 로컬에서 정상 빌드된다는 사실은 CI가 같은 잠금 상태를 사용한다는 증거가 아닙니다. Apple은 Swift 패키지를 사용하는 CI 워크플로에서 잠금 파일을 다루는 방법을 안내합니다. Swift 패키지 CI 문서를 기준으로 프로젝트 상태와 실제 빌드 결과를 대조하세요.

자동으로 의존성을 다시 해석하거나 Package.resolved를 지우는 것을 기본 해결책으로 삼지 마세요. 잠금 상태를 바꾸면 원래 오류가 사라지더라도 팀이 검증하지 않은 버전 조합이 빌드에 들어갈 수 있습니다. 파일의 위치와 커밋을 확인한 뒤, 그 상태에서 재현되는지 먼저 확인합니다.

CocoaPods나 Carthage 같은 도구를 쓰는 프로젝트는 도구를 어느 단계에서 설치하는지, 설치 명령이 빌드 환경에서 실행되는지, 잠금 파일이 버전 관리에 포함됐는지 살펴보세요. Xcode Cloud 빌드 환경에 이미 도구나 로컬 상태가 있다고 가정하지 말고, 필요한 준비를 워크플로와 스크립트에서 명시적으로 수행할 수 있는지 확인합니다.

[ ] 실패한 빌드 보고서에서 가장 먼저 실패한 단계를 확인합니다.
[ ] 앱 저장소, Swift Package, 하위 모듈의 실제 저장소 주소를 대조합니다.
[ ] 각 저장소가 서로 다른 서비스나 인스턴스에 있는지 확인합니다.
[ ] 해당 저장소의 연결 상태와 빌드 보고서의 접근 승인 안내를 확인합니다.
[ ] Package.resolved의 위치, 현재 브랜치 포함 여부, 커밋 상태를 확인합니다.
[ ] 도구 설치 명령과 잠금 파일이 빌드 과정에 포함되는지 검증합니다.
[ ] 수정 후 같은 변경 사항으로 빌드를 다시 실행하고 실패 단계와 로그를 비교합니다.

사용자 스크립트와 네트워크 경계 점검

post-clone, pre-xcodebuild, post-xcodebuild 가운데 스크립트가 실제로 실행돼야 하는 시점을 확인하세요. 스크립트 파일명이나 경로가 문서에 적힌 구성과 일치하는지, 실행 결과가 실패 상태를 반환하는지, 필요한 파일이 그 시점에 준비돼 있는지 빌드 보고서로 점검합니다. 스크립트가 로컬 개발자의 관리자 권한이나 설정된 도구 상태에 기대고 있다면, 임시 빌드 환경에서도 같은 조건이 갖춰진다고 가정할 수 없습니다.

기업 프록시나 사설 네트워크에만 있는 저장소가 관련돼 있다면, 현재 워크플로가 실제로 해당 주소에 접근할 수 있는지 검증하세요. 환경 변수에 필요한 값이 전달되는지 확인하되, 토큰과 비밀번호가 출력 로그에 노출되지 않도록 마스킹 여부도 점검합니다. Apple은 워크플로에서 제공되는 환경 변수와 사용자 스크립트 동작을 별도로 설명합니다. 환경 변수 참고 문서와 워크플로 참고 문서를 따라 필요한 값과 사용 위치를 확인하세요.

스크립트에 인증 정보를 임시로 출력해 문제를 찾는 방식은 피하세요. 로그에 민감한 값이 남을 가능성이 있다면, 출력 내용을 먼저 제한하고 비밀 값이 표시되지 않는 상태에서 재현해야 합니다.

다음과 같은 경우에는 현재 워크플로의 설정만 반복해서 바꾸기보다 실행 환경의 요구를 다시 정리하세요.

빌드가 접근해야 하는 사설 네트워크 주소를 현재 실행 환경에서 검증할 수 없습니다.
필요한 도구 설치가 재현 가능하지 않고, 스크립트가 문서화되지 않은 로컬 상태에 의존합니다.
접근 제어, 비밀 정보 처리 또는 네트워크 경로를 팀의 운영 기준에 맞게 확인할 수 없습니다.

이 조건은 곧바로 Xcode Cloud를 대체해야 한다는 뜻이 아닙니다. 재현 가능한 테스트로 현재 요구와 워크플로의 경계를 먼저 확인한 뒤, 별도 맥 실행 환경이 필요한지 판단하세요.

자주 확인하는 비공개 의존성 질문

비공개 Swift Package의 접근 권한은 어디에서 확인하나요?
패키지 저장소의 실제 주소와 호스팅 위치부터 확인한 다음 Xcode Cloud의 저장소 연결 상태를 살펴봅니다. 빌드 보고서에 접근 승인 안내가 있는지도 확인하세요. 저장소가 연결돼 보이더라도 실제 빌드가 사용하는 인스턴스가 다를 수 있으므로, 해당 패키지를 가져오는 빌드에서 재현되는지 검증해야 합니다.

비공개 Git 하위 모듈은 어떻게 승인 상태를 점검하나요?
하위 모듈 주소와 저장소 위치를 주 저장소와 따로 확인합니다. 상위 저장소 연결만으로 하위 저장소 접근까지 확인됐다고 볼 수 없습니다. 실패 빌드에서 하위 모듈을 가져오는 단계와 접근 안내를 찾고, 해당 저장소 연결 상태를 확인한 뒤 같은 변경 사항으로 다시 빌드합니다.

기업 저장소가 여러 인스턴스에 있을 때는 무엇을 확인하나요?
앱 코드와 의존성 코드가 같은 서비스의 서로 다른 인스턴스에 있는지, 별도 서비스에 나뉘어 있는지 구분합니다. 각 저장소의 실제 주소와 연결 상태를 확인하고, 추가 접근이 필요한 인스턴스가 빌드 보고서에 나타나는지 살펴보세요. 처음 연결한 저장소 하나만 보고 전체 구성이 완료됐다고 판단하지 않는 것이 중요합니다.

Package.resolved가 없거나 커밋되지 않았다면 어떻게 하나요?
파일이 예상한 프로젝트 경로에 있는지, 현재 빌드 브랜치에 포함돼 있는지 확인합니다. 그다음 Apple의 Swift 패키지 CI 안내와 실제 빌드 보고서를 대조해 해석 상태를 점검하세요. 원인을 확인하기 전에 자동 해석을 강제하거나 잠금 파일을 삭제하면 팀이 검증하지 않은 의존성 상태로 바뀔 수 있습니다.

Xcode Cloud의 관리형 워크플로는 별도 실행 환경을 직접 운영하지 않아도 된다는 장점이 있습니다. 반면 실제 빌드가 요구하는 사설 네트워크 접근, 특정 도구 준비, 실행 상태의 확인 방식이 팀 요구와 맞지 않으면 환경 경계와 로그, 재현 절차를 다시 살펴야 합니다. 자체 맥 환경은 네트워크와 도구 구성을 직접 관리할 여지를 주지만, 패치와 접근 권한, 비밀 정보, 운영 상태도 팀이 책임져야 합니다. 환경별 선택 기준은 맥 빌드 환경 비교 안내에서 살펴볼 수 있습니다.

현재 빌드 보고서로 요구 사항을 특정한 뒤에도 사설 네트워크나 도구 체인을 실행 환경에서 확인할 수 없다면, 별도 맥에서 그 조건을 검증하는 방안을 검토하세요. zshmac의 원격 맥 환경 안내를 확인하고 실제 저장소 접근 경로와 필요한 도구를 먼저 대조하면 됩니다. 현재 환경에서 요구를 충족하고 운영 부담이 더 낮다면 그대로 유지하는 편이 낫습니다. 반대로 임시 검증이나 별도 빌드 환경이 필요할 때는 요구 조건을 확인한 뒤 선택하세요.

자주 묻는 질문

비공개 Swift Package에 대한 접근 권한은 어디서 확인해야 하나요?

먼저 패키지 저장소가 앱 저장소와 같은 코드 호스팅 서비스에 있는지, 별도의 서비스나 인스턴스에 있는지 확인합니다. 그다음 Xcode Cloud의 코드 저장소 연결 상태와 실패한 빌드 보고서의 접근 승인 안내를 살펴보세요. 저장소 주소가 맞더라도 해당 저장소 연결이 승인되지 않았다면 가져오기가 실패할 수 있으므로, 추정만으로 권한 문제라고 단정하지 말고 빌드에서 재현되는지 확인합니다.

비공개 Git 하위 모듈을 빌드에서 사용하려면 무엇을 점검해야 하나요?

하위 모듈의 실제 저장소 주소와 이를 호스팅하는 서비스를 확인한 뒤, Xcode Cloud가 앱 코드 저장소뿐 아니라 하위 모듈 저장소에도 접근할 수 있는지 점검합니다. 하위 모듈 경로가 상대 주소인지, 빌드 중 인증이 필요한 주소인지도 저장소 설정과 빌드 로그에서 확인하세요. 오류 한 줄만으로 인증 실패를 확정하지 말고, 저장소 연결을 확인한 다음 같은 커밋으로 다시 빌드해 결과를 비교합니다.

기업 코드 저장소가 여러 인스턴스에 나뉘어 있으면 어떻게 연결하나요?

앱 코드와 의존성이 같은 서비스의 서로 다른 인스턴스에 있는지, 아니면 서로 다른 코드 호스팅 서비스에 있는지 먼저 구분합니다. 초기 연결 때 한 인스턴스를 승인했더라도 다른 인스턴스의 저장소 접근은 별도로 확인해야 합니다. 해당 저장소가 사용되는 빌드의 보고서에 추가 접근 안내가 나타나는지 살펴보고, 실제 의존성 저장소를 대상으로 연결 상태를 검증하세요.

Package.resolved가 없거나 커밋되지 않으면 빌드에 어떤 영향이 있나요?

Package.resolved의 유무와 저장 위치, 현재 브랜치에 포함된 커밋을 확인하세요. 파일이 예상한 프로젝트 경로에 없거나 변경 내용이 팀 저장소에 반영되지 않았다면, CI가 개발자의 로컬 환경과 다른 의존성 상태를 해석할 가능성을 점검해야 합니다. 파일을 무조건 다시 만들거나 자동 해석을 강제하기보다, Apple의 Swift 패키지 CI 안내와 실제 빌드 보고서를 기준으로 저장 상태와 해결 결과를 비교합니다.