Xcode 27 비공개 Swift Package 가져오기 실패? 2026 해결 가이드

CI에서만 비공개 Swift Package를 가져오지 못하고 로컬 빌드는 통과합니다.
이번 주에는 먼저 실제 CI 실행 계정의 SSH 키와 known_hosts를 확인하고, 그다음 Package.resolved와 의존성 주소를 대조합니다. 호스트 검증을 끄거나 캐시를 먼저 비우지는 않습니다.

이 글은 Xcode 프로젝트의 비공개 패키지 의존성을 원격 맥에서 빌드하는 개발자와 CI 노드를 관리하는 엔지니어를 위한 안내입니다. 로컬 환경에서 원격 환경으로 옮기는 모바일 개발 책임자도 계정 설정과 잠금 파일 문제를 구분할 수 있습니다.

오류 문구만 보고 인증 실패라고 단정하지 않습니다. 같은 커밋과 빌드 명령으로 로컬과 CI 로그를 비교해, 의존성 가져오기·SSH 인증·호스트 확인·버전 해결 중 어디서 멈추는지 먼저 분류합니다.

Apple의 Swift Package CI 구성 안내는 CI에서 비공개 의존성을 사용하려면 실행 환경에 인증 정보를 구성하고, SSH 의존성의 경우 해당 macOS 사용자 계정에 키와 known_hosts를 준비하도록 설명합니다. 관리자 로그인 세션에서 접속된다는 사실만으로 CI 작업에도 같은 자격 증명이 전달된다고 볼 수는 없습니다.

원격 맥에서 Xcode가 비공개 패키지를 가져오지 못하는 이유는 무엇인가요?
자주 놓치는 원인은 CI 작업의 실제 사용자와 키가 설치된 사용자가 다른 경우입니다. 다만 인증이 통과해도 호스트 키 검증이나 잠금 버전에서 별도로 실패할 수 있으므로, 로그의 첫 실패 단계를 기준으로 원인을 좁혀야 합니다.

Xcode 27의 배포 상태와 macOS 호환 조건은 모든 원격 노드에 동일하다고 가정하지 않습니다. Apple의 Xcode 시스템 요구 사항과 Xcode 27 릴리스 노트를 확인한 뒤 실제 노드의 조합을 기록합니다.

CI 작업 안에서 id -un과 echo "$HOME"을 실행해 실제 사용자와 홈 디렉터리를 기록합니다. 그다음 해당 계정이 SSH 설정 파일, 개인 키, SSH 에이전트에 접근할 수 있는지 확인합니다. 관리자가 터미널에서 성공한 결과는 CI 작업 계정의 접근 증거가 아닙니다.

SSH 키와 known_hosts는 어느 계정에 두어야 하나요?
빌드를 시작하는 CI 실행 계정의 SSH 환경에 두어야 합니다. Apple은 CI에서 SSH 의존성을 사용할 때 작업을 실행하는 macOS 계정에 자격 증명과 known_hosts를 구성하도록 안내합니다. Apple의 SSH 에이전트 기술 문서도 작업 프로세스가 사용할 수 있는 SSH 에이전트와 키의 관계를 확인할 때 참고할 수 있습니다.

키가 보이는지 확인할 때 비밀 키 내용을 출력하거나 전체 환경 변수를 로그에 남기지 않습니다. 저장소 접근 여부는 실행 계정에서 git ls-remote로 읽기 작업을 시험하는 편이 안전합니다. 배포 키를 선택할 수 있다면 읽기 전용 배포 키 권한 안내에 맞춰 대상 저장소에 필요한 최소 권한만 부여합니다.

인증 키가 있어도 원격 호스트의 신원을 확인할 수 없으면 연결은 중단될 수 있습니다. CI 실행 계정의 홈 디렉터리에 있는 .ssh/known_hosts와 패키지 저장소 URL을 함께 확인합니다. 키를 추가하기 전에는 공식 SSH 지문 안내처럼 신뢰할 수 있는 출처의 지문과 대조합니다.

호스트 키 검증 오류는 어떻게 처리하나요?
검증을 끄기보다 현재 저장된 호스트 키가 올바른지 확인하고, 필요하면 실행 계정의 known_hosts를 안전한 절차로 갱신합니다. 호스트 키 확인 오류 안내는 이런 오류를 별도로 다룹니다. StrictHostKeyChecking을 비활성화하면 잘못된 호스트에 연결해도 탐지하지 못할 수 있으므로 기본 해결책으로 삼지 않습니다.

OpenSSH의 클라이언트 설정 매뉴얼을 참고해 사용자별 호스트 규칙과 확인 옵션을 살피되, 문제를 재현한 설정만 한 번에 하나씩 바꿉니다. 불가피하게 검증을 우회해 시험했다면 접근 범위와 시간을 제한하고, 시험 직후 원래 설정을 복구해 정상 검증이 되는지 확인합니다.

저장소에 Package.resolved가 커밋되어 있는지 확인하고, 그 안의 비공개 의존성 주소가 CI 계정에서 접근 가능한 SSH URL과 일치하는지 살핍니다. 파일이 있어도 CI가 다른 작업 디렉터리나 프로젝트를 빌드한다면 기대한 잠금 결과가 적용되지 않을 수 있습니다.

Package.resolved를 커밋했는데 CI에서 다른 버전이 선택되면 어떻게 하나요?
먼저 같은 커밋의 파일이 CI 작업 공간에 존재하는지, 패키지 URL이 실제 접근 주소와 같은지 확인합니다. Apple은 CI에서 Swift Package를 빌드하는 지침에서 Package.resolved를 저장소에 포함하고, 직접 xcodebuild를 실행할 때 자동 의존성 해결을 비활성화해 잠금된 버전을 따르는 방법을 안내합니다.

따라서 인증 오류와 버전 불일치를 같은 문제로 처리하지 않습니다. 먼저 저장소 읽기가 가능한지 확인하고, 그다음 잠금 파일과 해석 결과를 비교합니다. 실패 원인을 모른 채 패키지를 갱신하면 원래 문제가 가려지고, 변경된 버전이 빌드 결과에 섞일 수 있습니다.

xcodebuild가 사용하는 Git 동작이 기대와 다른지 확인합니다. URL 재작성 규칙, 프록시, 사용자별 SSH 설정, SSH 에이전트 접근 여부를 한 항목씩 비교합니다. 시스템 Git 사용을 시험하는 경우에도 실제 로그가 Xcode 쪽 Git 설정 차이를 가리킬 때만 변경합니다.

xcodebuild가 CI 실행 계정의 SSH 설정을 사용하게 하려면 어떻게 하나요?
빌드 명령을 실행하는 프로세스가 올바른 사용자와 홈 디렉터리에서 시작되는지 확인하고, 그 계정의 SSH 설정과 에이전트가 작업 프로세스에 제공되는지 검사합니다. 관리자의 셸에서 성공한 명령을 그대로 CI에 복사하기보다 CI 로그에 id -un, HOME 값, 저장소 접근 결과를 남겨 차이를 확인합니다. 비밀 키 자체는 로그에 기록하지 않습니다.

매뉴얼의 OpenSSH 클라이언트 설정 항목을 기준으로 사용자 설정의 적용 범위를 점검합니다. 설정 변경 후에는 의존성 해석 로그와 실제 선택된 버전을 함께 보존합니다. SSH 설정, URL 재작성, 캐시를 동시에 바꾸면 어떤 수정이 효과가 있었는지 판단하기 어렵습니다.

깨끗한 작업 디렉터리에서 같은 커밋과 CI 실행 계정으로 다시 실행합니다. 아래 순서로 검증 결과를 기록합니다.

• [ ] 실제 작업 사용자와 HOME이 의도한 값입니다.
• [ ] 그 계정에서 비공개 저장소를 읽을 수 있습니다.
• [ ] 호스트 지문을 확인한 known_hosts가 그 계정에 있습니다.
• [ ] Package.resolved와 패키지 URL이 커밋 및 CI 환경에서 일치합니다.
• [ ] 의존성 해석과 빌드 로그를 함께 저장했습니다.

조건에 따라 다음처럼 결정합니다.

• 실행 계정이 읽기 권한이 있는 키를 안전하게 사용할 수 있다면, 그 계정의 SSH 설정을 바로잡고 같은 커밋으로 재검증합니다.
• 인증은 되지만 호스트 검증에서 멈춘다면, 지문을 검증해 known_hosts를 복구합니다. 검증 해제는 기본 대안으로 선택하지 않습니다.
• 잠금 파일이나 URL이 다르다면 먼저 저장소 상태와 CI 작업 경로를 바로잡습니다. 문제를 숨기려고 의존성을 무작정 갱신하지 않습니다.
• 공유 노드에서 키를 계정별로 분리할 수 없거나 권한 범위를 통제하기 어렵다면, 실행 계정을 분리하거나 격리된 빌드 노드로 옮깁니다.

공유 macOS 노드를 계속 쓰는 선택에는 계정 간 자격 증명 노출 가능성, 서로 다른 SSH 설정의 간섭, 재현하기 어려운 작업 환경이 따릅니다. 반면 독립 실행 계정이나 격리 노드는 관리 대상이 늘 수 있지만, 키 권한과 실패 원인을 더 분명히 구분할 수 있습니다. 현재 노드에서 접근 통제와 반복 검증이 가능하다면 그대로 유지하고, 그렇지 않다면 원격 맥 개발 환경 구성에 필요한 조건을 JEXCLOUD 안내와 대조해 보십시오.

Xcode 27의 구체적인 지원 상태와 시스템 요구 사항은 앞서 연결한 Apple의 현재 시스템 요구 사항과 릴리스 정보를 다시 확인해야 합니다. 로컬 맥은 정상인데 원격 CI만 실패한다면 먼저 실행 계정과 SSH 환경을 바로잡고, 잠금 파일까지 재현 검증한 뒤 노드 문제인지 판단하는 편이 안전합니다. 현재 환경에 통제 가능한 macOS 실행 노드가 없어 원인 재현과 계정 분리가 어렵다면, 기존 공유 노드의 권한 관리와 지속적인 설정 유지라는 부담을 고려해 JEXCLOUD의 원격 맥 대여 선택지를 비교할 수 있습니다. 장기간 상시 부하나 물리 장치 연결이 필요한 작업은 자체 맥 운용이 더 적합할 수 있으며, 임시 CI 노드나 격리된 재현 환경이 필요한 경우에 원격 대여를 검토하는 것이 합리적입니다.