SwiftPM 사설 의존성: 2026년 원격 맥 설정 가이드

그래픽 화면에서는 Xcode 빌드가 성공하지만, 같은 원격 맥의 백그라운드 작업은 사설 Swift 패키지를 가져오지 못합니다.

가장 빠른 해결책은 전용 저장소 자격 증명과 고정된 Package.resolved를 실제 빌드 사용자에게 연결하는 것입니다. 먼저 깨끗한 세션에서 의존성 해석만 검증한 뒤 컴파일과 보관으로 넘어가야 합니다.

이 글은 로컬 맥에서 원격 빌드 환경으로 옮기는 독립 개발자와 소규모 팀을 위한 안내서입니다. 명령줄이나 예약 작업으로 iOS 빌드를 실행한다면 비그래픽 세션의 SSH 접근을 중점적으로 확인해야 합니다. 여러 사설 저장소를 관리한다면 저장소별 권한과 키 교체 절차까지 함께 점검해야 합니다.

로컬 로그인 상태와 원격 빌드 사용자는 다릅니다

Xcode 화면에서 한 번 로그인했다고 해서 xcodebuild나 예약 작업이 같은 인증 상태를 얻는 것은 아닙니다. GUI 세션과 백그라운드 세션은 실행 사용자, 환경 변수, SSH 에이전트, 키체인 접근 방식이 다를 수 있습니다.

다음 세 가지 경계를 먼저 기록합니다.

• 프로젝트가 직접 참조하는 사설 패키지
• 다른 패키지를 통해 들어오는 전달 의존성
• 각 저장소에 필요한 최소 읽기 권한

Swift 패키지 의존성 선언 자체는 프로젝트의 패키지 설정에 남지만, 실제 저장소 인증은 빌드 환경이 담당합니다. 의존성 선언과 인증을 한 파일에 넣으려 하지 말고 분리해서 관리해야 합니다. 의존성 모델은 공식 Swift 패키지 의존성 문서에서 확인할 수 있습니다.

현재 로컬에서 성공한 커밋과 Package.resolved를 migration 기준으로 보관합니다. 기준 파일 없이 원격 환경을 먼저 실행하면 인증 문제와 버전 변경이 동시에 발생합니다.

첫 단계: 사설 저장소와 자격 증명을 분리합니다

개발용 키보다 전용 읽기 키가 안전합니다

개발자가 평소 사용하는 SSH 키에는 여러 저장소와 쓰기 권한이 묶여 있을 수 있습니다. 이를 원격 맥에 그대로 복사하면 패키지 하나를 읽기 위한 빌드 작업이 소스 변경이나 다른 저장소 접근 권한까지 얻게 됩니다.

원격 빌드에는 다음 조건을 적용합니다.

• 실제 빌드에 필요한 저장소만 읽도록 제한합니다.
• 개인 키는 프로젝트 파일과 스크립트에 기록하지 않습니다.
• 비밀번호와 토큰을 셸 명령의 인자로 넣지 않습니다.
• 공개 키만 저장소 쪽에 등록합니다.
• 키의 담당자, 용도, 교체 시점을 별도로 기록합니다.

SSH 키를 만들고 에이전트에 연결하는 일반 절차는 공식 SSH 키와 에이전트 안내를 기준으로 확인합니다. 여기서 중요한 것은 문서의 명령을 그대로 복사하는 일이 아니라, 키를 등록하는 주체가 실제 빌드 사용자여야 한다는 점입니다.

두 번째 단계: 실제 작업 사용자에게 SSH 설정을 둡니다

원격 맥에서 Xcode, xcodebuild, 예약 작업을 실행할 사용자를 먼저 정합니다. 그 사용자의 홈 폴더에서 SSH 설정과 호스트 검증 파일을 준비해야 합니다.

ssh -T git@저장소호스트
git ls-remote git@저장소호스트:조직/사설패키지.git

첫 명령은 SSH 인증과 호스트 확인을 나누어 살피는 데 사용합니다. 두 번째 명령은 실제 패키지 저장소의 읽기 가능 여부를 확인합니다. 저장소 주소는 프로젝트에 기록된 주소와 같아야 합니다. SSH 연결 테스트의 해석은 공식 SSH 연결 테스트 문서를 참고합니다.

known_hosts 검증 오류가 나오면 호스트의 공개 키를 확인한 뒤 정상적인 방식으로 등록합니다. 검증을 끄는 설정은 임시 진단에도 신중해야 하며, 장기 해결책으로 사용하면 안 됩니다.

이 단계의 실패 지점은 명확합니다.

• 키를 찾지 못하면 중단합니다.
• 호스트 검증이 실패하면 중단합니다.
• 저장소 읽기 권한이 없으면 중단합니다.
• 다른 사용자로 재시도해 성공한 결과는 통과로 인정하지 않습니다.

고정된 해석과 새로운 해석을 먼저 분리합니다

Package.resolved는 원격 환경이 의존성 버전을 임의로 다시 선택하지 않게 하는 기준입니다. 지속적인 통합 환경에서는 이 파일을 저장소에 포함해야 한다는 내용을 Swift 패키지 지속적인 통합 공식 안내에서 확인할 수 있습니다.

먼저 프로젝트 파일과 Package.resolved의 위치를 확인합니다. 프로젝트가 여러 개이거나 작업 폴더가 달라지면 파일이 있어도 다른 위치의 프로젝트가 읽을 수 있습니다.

그 다음 전체 빌드 전에 의존성 해석만 실행합니다.

xcodebuild -resolvePackageDependencies \
  -workspace 프로젝트.xcworkspace \
  -scheme 구성표

프로젝트가 워크스페이스가 아니라 프로젝트 파일을 사용하는 경우에는 해당 방식에 맞춰 명령을 바꿉니다. 명령줄 빌드의 기본 원칙과 인자는 공식 명령줄 빌드 기술 문서에서 재확인해야 합니다.

관찰할 결과는 세 가지입니다.

• 사설 패키지 저장소에 인증이 성공했는가
• 고정된 버전과 현재 해석 결과가 예상과 같은가
• 캐시를 지워도 같은 저장소와 버전을 읽는가

인증 실패는 SSH 설정을 다시 점검합니다. 버전 해석 실패는 패키지 선언과 Package.resolved 변경을 점검합니다. 둘을 동시에 수정하지 않아야 다음 실행에서 원인을 추적할 수 있습니다.

주의: 의존성 폴더에 남아 있는 캐시만으로 성공한 결과는 인증 검증이 아닙니다. 새 작업 폴더에서도 저장소에 접근해야 통과로 기록합니다.

FAQ: 인증, 잠금 파일, 무인 실행을 따로 확인합니다

앞 단계에서 해석이 통과했다면 자주 발생하는 운영 질문을 다음처럼 분리할 수 있습니다.

사설 패키지 인증은 어디에 적용해야 합니까?

실제 xcodebuild를 실행하는 사용자 환경에 SSH 설정을 둡니다. VNC로 로그인한 관리자와 예약 작업 사용자가 다르면 두 세션은 같은 설정을 보장하지 않습니다. 저장소에는 전용 공개 키만 등록하고, 개인 키와 암호는 프로젝트나 로그에 남기지 않습니다.

왜 화면에서는 되고 xcodebuild에서는 실패합니까?

화면의 Xcode가 보유한 로그인 상태나 키체인이 백그라운드 프로세스에 전달되지 않을 수 있습니다. 동일한 사용자, 동일한 작업 폴더, 동일한 저장소 주소로 git ls-remote와 의존성 해석을 먼저 실행해야 합니다. 이 검증이 실패한 상태에서 컴파일 옵션을 바꾸는 것은 순서가 아닙니다.

재시작 뒤 키가 사라졌다면 무엇을 봐야 합니까?

맥 재시작 뒤 SSH 에이전트가 키를 다시 제공하는지, 예약 작업이 같은 키체인과 홈 폴더를 보는지 확인합니다. SSH 키의 암호와 에이전트 사용 방식은 공식 SSH 암호 및 에이전트 문서를 기준으로 검토합니다.

Package.resolved는 꼭 커밋해야 합니까?

원격 보관과 지속적인 통합이 목적이면 커밋하는 편이 안전합니다. 의존성 업데이트 때만 의도적으로 파일을 바꾸고, 변경 내용을 검토한 뒤 원격에서 다시 해석합니다. 파일이 없거나 다른 프로젝트 위치에 있으면 실행 시점에 새로운 버전이 선택될 가능성이 생깁니다.

무인 실행에는 어떤 순서가 적합합니까?

키 로드와 저장소 읽기부터 확인한 뒤 의존성 해석, 컴파일, 보관을 순서대로 실행합니다. 사설 패키지 읽기 키와 코드 서명 및 배포 자격 증명은 분리합니다. 키가 없거나 호스트 검증에 실패하면 작업을 계속하지 않고 로그를 남긴 뒤 중단해야 합니다.

세 번째 단계: 같은 사용자로 명령줄 빌드를 재현합니다

의존성 해석이 통과한 뒤에야 컴파일과 보관을 실행합니다. 이때도 Xcode 화면에서 성공한 결과를 대신 사용하지 않습니다. 이후 자동 작업이 사용할 사용자와 폴더에서 실제 프로젝트를 실행합니다.

점검 순서는 다음과 같습니다.

1. 작업 폴더를 정하고 저장소 상태를 기록합니다.
2. 선택한 빌드 사용자가 사설 패키지를 읽는지 다시 확인합니다.
3. Package.resolved가 예상한 파일인지 확인합니다.
4. 의존성 해석 로그와 대상 컴파일 결과를 따로 보관합니다.
5. 배포용 보관 작업을 실행합니다.
6. 보관 파일과 실패 로그의 접근 권한을 확인합니다.

보관과 내보내기 절차는 공식 보관 및 내보내기 안내를 기준으로 프로젝트 유형에 맞게 조정합니다. 사설 패키지 인증과 코드 서명 인증을 같은 비밀 저장소에 넣으면 실패 원인과 권한 범위가 모두 불분명해집니다.

저장소 주소를 바꾸거나 Git 프록시, URL 치환, 고급 SSH 설정이 필요한 경우에는 먼저 기본 SSH 접근을 통과시킵니다. 그 다음에만 명령줄 소스 관리 옵션을 추가합니다. 설정을 한 번에 여러 개 바꾸면 어느 설정이 인증을 해결했는지 확인할 수 없습니다.

네 번째 단계: 무인 세션과 재시작을 별도로 시험합니다

VNC 연결이 끊긴 뒤에도 작업이 끝나는지 확인해야 합니다. SSH 접속이 열린 상태에서만 성공하는 구성은 상시 빌드 서버가 아닙니다.

다음 조건을 차례로 재현합니다.

• VNC 없이 실행합니다.
• SSH 연결을 끊은 뒤 실행합니다.
• 예약 작업과 같은 사용자로 실행합니다.
• 의존성 캐시를 재사용하지 않는 작업 폴더에서 실행합니다.
• 맥을 재시작한 뒤 다시 실행합니다.

재시작 뒤에는 키체인, SSH 에이전트, 환경 변수, 호스트 검증 파일을 각각 확인합니다. 암호를 입력할 수 없는 예약 작업에서 키가 자동으로 제공되지 않는다면 작업을 실패시키는 편이 안전합니다. 개인 키를 평문 환경 변수로 우회하거나 호스트 검증을 해제하는 방식은 재현성이 아니라 보안 부채를 만듭니다.

현재 방식과 원격 맥의 선택 기준

이미 개인 맥에서 모든 작업을 처리하는 방식은 초기 설정이 단순합니다. 반면 장시간 켜 두어야 하고, 디스크와 계정 상태가 개인 환경에 묶이며, 개발자 퇴근 뒤 자동 작업을 관리하기 어렵습니다. 일반적인 일회성 클라우드 빌드는 작업마다 인증과 캐시를 다시 준비해야 하고, 사설 저장소 접근이 실행 환경에 따라 달라질 수 있습니다.

선택지	인증 관리	의존성 재현성	적합한 경우	주의할 점
개인 맥에서 수동 실행	개인 계정에 의존하기 쉬움	작업자 상태에 영향 받음	작은 실험과 즉시 수정	상시 보관과 교대 작업에 약함
일회성 클라우드 빌드	실행 환경별 설정 필요	캐시와 세션 차이 점검 필요	짧은 검증 작업	사설 저장소 인증을 별도 설계
상시 원격 맥	전용 빌드 사용자로 분리 가능	Package.resolved와 작업 폴더를 고정	반복 보관과 무인 실행	키 교체와 재시작 시험 필요
자체 보유 맥 미니	물리 장비를 직접 관리	환경을 오래 유지 가능	장기 고정 부하와 장비 접근	구매 비용, 유지 보수, 장애 대응 필요

원격 맥을 선택하더라도 모든 프로젝트에 정답은 아닙니다. 물리 USB 장치가 필요하거나 장기간 매우 높은 부하가 일정하게 발생하면 자체 장비가 더 적합할 수 있습니다. 반대로 시험, 이전, 단기 출시 준비처럼 기간이 유동적이면 ProxyMac 이용 안내에서 접속 방식과 운영 조건을 먼저 확인하는 편이 낫습니다.

검증 시점	성공 기준	실패 시 중단할 작업
저장소 접근	실제 빌드 사용자가 사설 저장소를 읽음	의존성 해석
의존성 해석	고정 파일과 예상 버전이 일치함	컴파일
대상 컴파일	사설 패키지와 앱 대상이 함께 통과함	보관
보관	서명 단계와 보관 결과를 추적할 수 있음	무인 등록
재시작 후 재실행	캐시나 그래픽 로그인 없이 같은 흐름이 재현됨	장기 예약 작업

장기 사용을 검토한다면 ProxyMac 콘솔에서 실제 프로젝트를 짧은 기간 먼저 검증하는 방식이 안전합니다. 특히 키 교체, 저장소 제거, 빌드 사용자 변경, Xcode 업데이트 뒤에는 같은 표를 다시 실행해야 합니다.

마무리: 냉시작 검증 뒤에 장기 작업을 등록합니다

로컬 맥만 사용하는 방식은 개인 로그인 상태에 의존하고, 장비를 계속 켜 두어야 하며, 디스크와 유지 보수 비용을 한 사람이 떠안기 쉽습니다. 일회성 클라우드 빌드는 실행마다 사설 저장소 인증과 캐시 상태를 다시 확인해야 합니다. 이 조건이 반복된다면 실제 프로젝트를 원격 맥에서 냉시작 해석, 보관, 재시작 후 재실행까지 시험하는 편이 더 정확합니다.

전용 키와 고정된 Package.resolved가 무인 상태에서도 유지될 때만 장기 iOS 보관 작업에 연결해야 합니다. 짧은 기간의 검증 환경이 필요하다면 ProxyMac 요금 및 이용 조건을 확인한 뒤, 개인 장비를 바로 구매하기 전에 실제 사설 패키지 흐름부터 재현해 보는 것이 합리적입니다.