로컬에서는 되는데 원격 빌드가 비공개 Swift 패키지를 가져오지 못합니다. 먼저 원격 작업이 쓰는 저장소 주소, 실제 macOS 실행 계정과 인증 정보 출처를 확인하고, Package.resolved가 버전 관리에 포함됐는지 검증하세요. Xcode Cloud와 자체 관리 맥은 인증 설정 방법이 다릅니다.
로컬 빌드는 통과하지만 원격 맥의 의존성 분석에서 멈춘 독립 개발자라면, 로컬 자격 증명과 CI 실행 계정의 차이를 확인할 수 있습니다. 자체 관리 Runner를 운영한다면 SSH 키와 호스트 확인 설정을 점검하세요. Xcode Cloud에 비공개 패키지를 연결한 팀이라면 플랫폼의 접근 승인 절차와 자체 관리 환경의 설정을 구분하세요.
실패 단계와 실행 계정 확인
먼저 실패가 Swift 코드 컴파일 전인지 후인지 나누세요. 빌드 보고서나 xcodebuild 로그에서 처음 실패한 작업을 찾고, 실행 계정과 작업 디렉터리, 빌드 시작 방법을 함께 기록합니다. 최종 상태가 실패라는 사실만으로 인증 오류라고 단정하면 안 됩니다. 의존성 주소 오류, 네트워크 차단, 버전 확인 실패, 컴파일 오류는 서로 다른 조치가 필요합니다.
Apple의 Xcode 명령줄 도구 안내에서 사용하는 명령의 옵션을 확인하고, 일반적인 설정 및 빌드 문제 안내와 대조해 최초 실패 지점을 분류하세요.
로컬에서는 패키지가 확인되는데 원격 맥에서는 실패한다면 무엇을 먼저 볼까요? 원격 작업을 실행한 macOS 계정과 그 계정이 실제로 읽을 수 있는 인증 정보를 먼저 확인하세요. 개발자 계정의 터미널에서 성공했더라도 서비스 계정이나 자동화 Runner가 같은 SSH 키와 Git 설정을 사용한다는 뜻은 아닙니다.
저장소 주소와 접근성 검증
프로젝트 설정, Package.swift, 잠금 파일에 기록된 의존성 출처를 서로 대조하세요. 원격 작업이 의도한 SSH 또는 HTTPS 주소에 접근하는지 확인합니다. 주소가 올바른지, 네트워크에서 호스트에 도달하는지, 지정된 저장소와 브랜치 또는 태그가 존재하는지는 각각 따로 검사해야 합니다.
| 확인 지표 | 증거 확인 위치 | 다음 조치 |
|---|---|---|
| 최초 실패 단계 | 빌드 보고서와 xcodebuild 로그 | 패키지 확인 실패와 컴파일 실패를 구분합니다 |
| 저장소 주소와 네트워크 | 프로젝트 설정, Package.swift, 원격 작업 로그 | 주소와 네트워크 경로를 따로 검증합니다 |
| 계정과 인증 정보 | 작업을 시작한 계정의 SSH 및 Git 설정 | 해당 계정에서 접근을 재현합니다 |
| 의존성 버전 | Package.resolved와 버전 관리 기록 | 원격 빌드에서 선택된 버전을 비교합니다 |
계정별 인증과 실행 환경 구분
자체 관리 맥에서는 xcodebuild를 실제로 실행하는 사용자를 확인한 뒤, 그 사용자에게 SSH 키와 ssh-agent, known_hosts, Git 설정이 제공되는지 점검합니다. 대화형 터미널에서만 불러오는 환경 변수나 에이전트에 의존하면, 비대화형 빌드 작업에서 인증이 이어지지 않을 수 있습니다. Apple의 소스 코드 관리 설정 안내에 따라 Xcode가 사용하는 소스 관리 인증 흐름도 살펴보세요.
반면 Xcode Cloud는 자체 관리 맥의 SSH 설정을 그대로 복사하는 환경이 아닙니다. Xcode Cloud에서 의존성을 사용할 수 있도록 설정하는 안내의 SCM 승인 흐름을 따라야 합니다. Xcode Cloud와 소스 코드 저장소 연결 안내도 함께 확인하고, 현재 프로젝트의 저장소 연결 상태와 승인된 접근 범위를 검증하세요.
| 빌드 환경 | 인증을 확인할 곳 | 적합한 점검 방법 |
|---|---|---|
| 자체 관리 원격 맥 | 작업 실행 계정의 SSH 키, 에이전트, 호스트 확인 설정 | 동일 계정과 동일한 빌드 시작 방식으로 저장소 접근을 재현합니다 |
| Xcode Cloud | Xcode Cloud의 SCM 승인과 연결된 저장소 접근 | 플랫폼의 비공개 의존성 승인 흐름에서 접근 권한을 확인합니다 |
xcodebuild에서 SSH 인증을 확인하려면 어떻게 해야 할까요?** 개발자 계정이 아니라 자동화 작업을 실행하는 계정으로 저장소 접근을 점검하세요. 예를 들어 git ls-remote '<비공개 저장소 주소>'를 실행해 원격 저장소에 닿는지 확인할 수 있습니다. 실제 주소나 자격 증명은 명령 기록과 로그에 노출되지 않도록 가리고, 접근 결과와 빌드 로그를 함께 비교하세요.
Package.resolved와 버전 재현성 확인
Package.resolved가 프로젝트에서 요구하는 위치에 있는지, 변경 사항이 버전 관리에 포함됐는지 확인하세요. 로컬에서 이미 받아 둔 패키지가 남아 있으면 잠금 파일이 빠졌거나 변경된 상황이 드러나지 않을 수 있습니다. 원격 작업이 실제로 해석한 버전과 팀이 기대하는 버전을 비교하고, 의존성 선언과 잠금 파일이 함께 검토되도록 관리하세요.
Apple은 CI에서 Package.resolved를 사용해 패키지 버전을 고정하는 흐름을 안내합니다. Swift 패키지를 사용하는 앱의 CI 빌드 안내를 기준으로 빌드 환경을 확인하세요. Xcode의 동작 대신 macOS Git 설정이 필요한 경우에는 사용 중인 Xcode와 환경에 적용되는 방식을 먼저 문서에서 확인해야 합니다.
Package.resolved를 제출하지 않으면 원격 빌드가 다른 버전을 선택할 수 있나요? 잠금 정보가 원격 작업에 전달되지 않으면 기대한 버전과 다른 의존성 상태가 만들어질 수 있습니다. 다만 실제 결과는 프로젝트 설정과 빌드 환경에 따라 달라지므로, 파일을 무조건 다시 만들기보다 저장소에 기록된 파일과 실패 작업의 해석 결과부터 비교하세요. 인증 문제를 숨기려고 강제 자동 해결을 적용하지 마세요.
비밀 정보와 변경 범위 관리
토큰이나 개인 키가 저장소, 스크립트 출력, 빌드 로그, 저장소 URL에 포함되지 않았는지 확인하세요. 접근 권한은 빌드에 필요한 저장소 범위로 제한하고, 노출이 의심되면 설정을 지우기 전에 교체 계획을 세우세요. 키 삭제, 공유 Git 설정 수정, 캐시 정리는 다른 작업에도 영향을 줄 수 있습니다. 변경 대상과 되돌리는 방법을 먼저 기록한 뒤 적용하세요.
다음 항목을 모두 확인하기 전에는 빌드 캐시를 삭제하거나 의존성을 강제로 다시 해석하지 마세요.
- [ ] 실패한 빌드의 시작 방식, 작업 디렉터리, 실제 macOS 실행 계정을 기록했습니다.
- [ ] 프로젝트의 의존성 주소와 원격 작업이 접근하는 주소가 일치합니다.
- [ ] 해당 계정에서 네트워크 접근, 저장소 경로, 대상 브랜치 또는 태그를 각각 확인했습니다.
- [ ] 자체 관리 맥의 SSH 인증 또는 Xcode Cloud의 SCM 승인을 해당 환경에 맞게 검증했습니다.
- [ ]
Package.resolved의 위치와 버전 관리 상태를 확인하고, 기대 버전과 비교했습니다. - [ ] 비밀 정보의 노출 여부와 교체 범위, 변경 전 설정으로 되돌리는 방법을 기록했습니다.
- [ ] 실제 운영 작업과 같은 계정 및 빌드 경로에서 의존성 확인과 최종 빌드를 재현했습니다.
동일 조건의 깨끗한 빌드로 마무리
복구 후에는 운영 환경과 같은 계정, 저장소 접근 방식, 빌드 진입점으로 검증하세요. 의존성 접근 성공, 잠금된 버전과 기대 버전의 일치, 최종 빌드 통과를 각각 증거로 남깁니다. 세 결과를 분리해 기록해야 이후 인증 만료와 버전 변경을 구별할 수 있습니다. 확인이 끝난 뒤에만 불필요한 임시 자격 증명을 정리하세요.
| 검증 결과 | 통과로 볼 근거 | 실패 시 되돌아갈 점검 |
|---|---|---|
| 저장소 접근 | 실제 빌드 계정에서 저장소 확인 성공 | 주소, 네트워크, 계정별 인증 |
| 버전 일치 | 원격 작업의 해석 결과가 잠금 정보와 일치 | Package.resolved 위치와 버전 관리 상태 |
| 최종 빌드 | 같은 운영 경로에서 의존성 확인부터 빌드까지 완료 | 최초 실패 로그와 환경 차이 |