CocoaPods 공식 가이드는 pod install과 pod update를 서로 다른 두 명령으로 설명합니다. 명령별 동작 기준에 따라, CocoaPods 원격 Mac CI 설치 실패를 조사할 때는 먼저 Runner가 실제 호출한 Ruby와 Bundler를 확인하고 실패 단계를 좁혀야 합니다. 잠금 파일을 보존한 채 원래 커밋을 재현하세요. 먼저 pod update를 실행하거나 로그를 보지 않고 캐시를 지우지 마세요.

이 글은 GitHub Actions를 비롯한 macOS CI를 관리하며 로컬과 Runner의 환경 차이를 찾아야 하는 엔지니어를 위한 안내입니다.
비공개 Pod 저장소를 쓰는 팀은 실행 계정의 접근 권한과 자격 증명 주입을 점검할 수 있습니다.
의존성 버전을 유지하면서 수정 결과를 같은 커밋으로 검증하려는 개발자와 빌드 담당자도 대상입니다.

01

실패 지점부터 구분: 명령 실행과 의존성 해결은 다릅니다

로컬에서 설치가 끝나고 원격에서 실패하더라도 원인이 프로젝트 파일이라고 단정할 수 없습니다. 실행 계정, 현재 작업 디렉터리, 셸 종류, 명령 진입점이 다르면 같은 저장소에서도 호출되는 도구와 읽히는 설정이 달라질 수 있습니다.

먼저 CI 로그에서 실패한 마지막 명령과 그 직전의 작업을 확인하세요. 오류가 CocoaPods 명령을 시작하기 전에 발생했는지, Specs를 조회하는 중인지, Pod 소스를 내려받는 중인지, Xcode 작업공간을 만든 뒤인지 구분합니다. 전체 로그를 보존하고 동일한 커밋에서 로컬 로그와 나란히 비교하세요.

로그에서 보이는 증상 우선 의심할 구간 다음 확인
pod를 찾지 못하거나 Ruby 실행 오류가 발생함 PATH와 Ruby 환경 실행 계정, 셸 초기화, which ruby, which pod
Specs 조회나 연결 단계에서 중단됨 소스 설정 또는 네트워크 Podfile의 source, 실제 응답과 연결 오류
비공개 Pod를 찾거나 내려받지 못함 저장소 주소와 인증 Spec 저장소 및 소스 저장소의 읽기 권한
설치는 끝났지만 빌드가 실패함 Xcode 통합 또는 빌드 설정 생성된 작업공간과 별도 Xcode 빌드 로그

질문: 로컬에서는 pod install이 되는데 원격 Mac CI에서는 왜 실패하나요?

두 환경이 같은 도구를 같은 계정과 디렉터리에서 실행하는지부터 확인해야 합니다. 로컬 터미널에서 성공했다는 사실만으로 CI의 PATH, 네트워크 접근, 키체인 또는 저장소 권한까지 같다고 볼 수는 없습니다. 오류가 나온 단계와 실행 환경을 비교하면 프로젝트 설정 문제와 Runner 환경 문제를 분리할 수 있습니다.

로그를 공유할 때는 저장소 주소에 포함된 사용자 정보, 토큰, 개인 경로를 가리세요. 오류 문맥은 남기되 인증 정보는 삭제해야 합니다.

02

실행 도구 비교: 시스템 Ruby와 프로젝트 Bundler를 구별합니다

macOS CI는 로그인 셸과 비대화형 셸에서 PATH가 달라질 수 있습니다. 또한 셸 설정 파일에만 등록한 Ruby 경로는 CI 실행 계정에서 읽히지 않을 수 있습니다. ruby, gem, bundle, pod가 각각 어디서 오는지 같은 작업 단계에서 출력하세요.

CocoaPods 설치 안내와 Gemfile 및 Bundler 안내는 프로젝트 의존 도구를 정하고 실행하는 방법을 설명합니다. 프로젝트에 Gemfile과 Gemfile.lock이 있다면 설치 단계에서 이를 사용하고, pod도 bundle exec pod install로 호출하는지 확인하세요. 시스템 전역에 설치한 CocoaPods가 프로젝트가 고정한 버전과 다르면 로컬과 CI의 결과가 달라질 수 있습니다.

확인 항목 프로젝트 고정 방식 전역 도구 방식에서 생기는 위험
Ruby와 Gem 의존성 Gemfile 및 Gemfile.lock 확인 다른 Ruby나 Gem이 선택될 수 있음
CocoaPods 실행 bundle exec pod install PATH에서 예상 밖의 pod가 실행될 수 있음
실행 환경 CI 단계에서 경로와 버전 기록 터미널 설정에 의존해 재현이 어려움

질문: 원격 Mac이 올바른 Ruby나 pod 명령을 찾지 못하면 어떻게 하나요?

실패한 CI 단계에서 아래 정보를 출력하고, 실행 계정과 현재 디렉터리를 함께 기록하세요. 출력 결과가 로컬과 다르면 프로젝트 파일을 바꾸기 전에 PATH와 셸 초기화부터 바로잡습니다.

whoami
pwd
echo "$PATH"
which ruby
ruby --version
which gem
gem --version
which bundle
bundle --version
which pod
pod --version

명령이 bundle을 찾지 못하면 Bundler 설치 경로와 선택된 Ruby를 확인하세요. Gemfile이 있는데도 일반 pod install을 실행하고 있다면 CI 명령을 프로젝트의 Bundler 환경으로 맞춥니다. CocoaPods 명령 참고에서 실행 명령의 용도를 대조할 수 있습니다.

03

Specs와 CDN 비교: 연결 장애와 소스 설정 오류를 나눕니다

Specs 조회 실패 메시지만으로 CDN 장애라고 결론 내리면 안 됩니다. Pod 이름이나 버전이 설정된 소스에 없을 수도 있고, TLS 협상이나 DNS 조회, 프록시 정책, 네트워크 연결에서 막힐 수도 있습니다. 오류 종류와 해당 단계의 실제 로그를 근거로 구별하세요.

확인할 증거 설정 또는 연결 문제를 가르는 방법 대응
Podfile의 source 항목 필요한 공개 또는 사설 Specs 소스가 지정됐는지 확인 의도한 소스 구성을 검토
오류의 HTTP 및 TLS 문맥 응답 코드, 인증서, 연결 실패 문구를 원문으로 보존 Runner에서 같은 주소 접근을 재확인
Pod 이름과 버전 요청한 항목이 설정된 소스와 버전에 존재하는지 점검 Podfile과 Spec 정의를 대조
로컬과 CI의 결과 차이 같은 커밋과 소스 설정으로 비교 차이가 난 네트워크 경로를 확인

질문: Specs CDN 다운로드 실패가 네트워크 문제인지 소스 설정 문제인지 어떻게 판단하나요?

먼저 Podfile의 소스 설정 문서와 실제 저장소 설정을 대조하세요. 이어서 실패한 Runner에서 로그에 나온 주소로의 연결 결과와 TLS 관련 오류를 확인합니다. 연결이 성립했지만 원하는 Pod나 버전을 찾지 못했다면 설정 또는 Spec 정의를 더 살펴야 합니다. 단 한 번의 실패만으로 상위 소스나 CDN의 현재 상태를 단정하지 마세요.

CocoaPods의 문제 해결 안내는 진단 참고 자료로 사용할 수 있습니다. 다만 문서만으로 현재 Runner의 네트워크 상태가 확인되지는 않습니다. 근거가 되는 것은 당시의 CI 로그와 같은 조건에서 다시 실행한 결과입니다.

04

비공개 Pod 비교: Specs 접근과 소스 코드 접근을 따로 확인합니다

비공개 Pod는 Spec을 읽는 저장소와 실제 소스 코드를 가져오는 저장소가 다를 수 있습니다. Spec을 찾았다는 이유만으로 소스 저장소 접근까지 성공했다고 볼 수 없습니다. CI에서 실행되는 계정에 각 저장소를 읽을 권한이 있는지 별도로 확인하세요.

접근 단계 확인할 내용 안전한 검증
Spec 저장소 저장소 주소와 Podfile의 참조가 일치하는지 실행 계정으로 읽기 작업 수행
Pod 소스 저장소 Spec에 적힌 소스 주소에 접근 가능한지 CI에서 저장소 조회 결과 확인
인증 정보 주입 필요한 비밀 값이 해당 작업에 전달되는지 값 자체를 출력하지 않고 존재 여부만 점검
권한 범위 읽기에 필요한 권한만 부여됐는지 저장소별 접근 정책 확인

질문: CI가 비공개 Pod 저장소에 접근하지 못하면 무엇을 점검하나요?

먼저 비공개 CocoaPods 저장소 안내에 맞춰 Specs 저장소 등록과 Podfile 참조를 점검하세요. 다음으로 CI 실행 계정이 Spec 저장소와 소스 저장소를 각각 읽을 수 있는지 확인합니다. 자격 증명은 CI 비밀 저장소에서 주입하고, 예시에는 $PRIVATE_REPO_TOKEN 같은 자리표시자만 쓰세요. 토큰을 명령행 인수나 로그에 남기지 말고, 권한이 필요한 작업에만 전달합니다.

05

잠금 파일 유지: 설치 오류와 의존성 업데이트를 섞지 않습니다

Podfile.lock은 설치할 의존성 버전을 재현하는 기준입니다. 저장소에 포함되어 있는지, CI가 올바른 디렉터리에서 실행되는지, 설치 명령이 잠금 결과를 따르는지 확인하세요. 잘못된 작업 디렉터리에서는 잠금 파일이 존재해도 기대한 파일을 읽지 못할 수 있습니다.

CocoaPods의 명령 구분 안내에 따르면 pod install은 잠금 파일의 버전을 사용하고, pod update는 의존성 버전을 갱신하는 데 쓰입니다. 따라서 설치 실패를 고치겠다며 먼저 업데이트하면 원래 실패와 버전 변경이 한꺼번에 섞입니다.

명령 또는 상태 역할 장애 조사에서의 사용
pod install 잠금 파일을 기준으로 설치 원래 커밋의 설치 재현
pod update 지정한 의존성의 버전 갱신 의도한 의존성 변경을 별도 작업으로 수행
Podfile.lock 누락 또는 미반영 같은 의존성 조합을 보장하기 어려움 버전 관리 상태와 작업 디렉터리 확인

버전을 바꿔야 한다면 설치 문제 수정과 분리된 변경으로 처리하세요. 업데이트 뒤에는 잠금 파일의 변경 내용을 검토하고, 해당 변경이 필요한 이유를 기록합니다. 캐시 삭제도 최초 조치로 삼지 마세요. 먼저 로그와 잠금 파일을 보존해야 이전 상태를 비교하고 원인을 좁힐 수 있습니다.

06

설치 이후 분리 검증: Pods 생성과 Xcode 빌드를 따로 봅니다

pod install 명령이 성공했다면 의존성 설치와 Xcode 빌드가 모두 성공했다는 뜻은 아닙니다. Pods 프로젝트와 작업공간 통합이 만들어졌는지 확인한 뒤, Xcode 빌드 로그를 별도 단계로 살펴보세요. 오류가 서명, 빌드 설정, 소스 코드 중 어디서 시작됐는지 구분해야 합니다.

복구 검증은 원래 커밋, 같은 Podfile.lock, 수정한 Runner를 사용해 진행합니다. 결과에는 실제 실행 계정, 작업 디렉터리, 도구 경로, 설치 명령, 설치 종료 상태와 후속 빌드 결과를 남기세요. 여전히 실패하면 새 노드를 만드는 대신 문제가 재현된 로그 단계로 돌아갑니다.

실행 전에 확인할 항목

  • [ ] 원래 실패한 커밋과 CI 로그를 보존했습니다.
  • [ ] 실패가 명령 실행, Specs 조회, 저장소 인증, 소스 다운로드, Xcode 빌드 중 어디인지 구분했습니다.
  • [ ] CI의 실행 계정, 작업 디렉터리, 셸과 PATH를 기록했습니다.
  • [ ] Ruby, RubyGems, Bundler와 CocoaPods의 실제 경로와 버전을 확인했습니다.
  • [ ] Gemfile이 있다면 프로젝트의 Bundler 환경으로 CocoaPods를 실행합니다.
  • [ ] Podfile.lock이 버전 관리에 포함됐는지, 올바른 디렉터리에서 읽히는지 확인했습니다.
  • [ ] 비공개 Specs 저장소와 Pod 소스 저장소의 읽기 권한을 각각 검증했습니다.
  • [ ] 토큰과 비밀 값이 로그, 명령 인수, 예시 파일에 노출되지 않았습니다.
  • [ ] 수정 뒤 원래 커밋과 잠금 파일로 설치와 Xcode 빌드를 따로 재검증했습니다.

CocoaPods 프로젝트 저장소는 프로젝트가 유지 관리 모드에 있다고 표시합니다. 이는 특정 오류가 모두 해결 불가능하다는 뜻이 아닙니다. 현재 상태를 단정하기보다 공식 문서와 당시 로그, 재현 결과를 기준으로 판단하세요.

로컬 macOS에서 공통 코드와 비의존 작업을 처리하는 방식은 이미 Mac이 있고 작업이 간헐적일 때 합리적입니다. 반면 Linux CI만으로는 macOS 전용 도구 체인에서 실행되는 단계를 직접 확인할 수 없고, Xcode 작업공간 통합이나 서명 관련 환경 차이도 검증하기 어렵습니다. 장기적으로 고정된 고부하 작업이 계속되거나 물리 장치 연결이 필요하다면 자체 Mac 노드가 더 알맞을 수 있습니다. 다만 프로젝트 설정이 잘못된 상태에서는 원격 Mac으로 옮겨도 같은 설치 실패가 반복됩니다.

환경 차이를 배제했는데도 안정적인 macOS 실행 환경이 없다면 MESHLAUNCH 원격 Mac을 CI 주기와 도구 체인에 맞춰 검토할 수 있습니다. 먼저 맥 미니 대여 가격과 이용 방식을 확인하고, 필요한 기간과 접근 방식을 비교하세요. 서비스의 기본 이용 경로는 MESHLAUNCH 안내에서 살펴볼 수 있습니다.