로컬 Mac 없이 Kotlin Multiplatform iOS 앱을 빌드할 수 있나요?

공유 Kotlin 코드와 대부분의 Gradle 검사는 Windows나 Linux에서 진행할 수 있습니다. 그러나 iOS용 Framework 연결, Apple 시뮬레이터 실행, Xcode 테스트, Archive와 서명은 macOS가 필요합니다. 따라서 로컬 Mac이 없다면 완전한 대체 환경보다 Xcode가 설치된 실제 원격 Mac을 Apple 빌드 노드로 분리하는 구성이 안전합니다.

Kotlin Multiplatform에서 macOS가 필요한 iOS 작업은 무엇인가요?

Kotlin/Native 바이너리 생성만이 아니라 iOS Framework를 Xcode 프로젝트에 연결하고, 기기 또는 시뮬레이터 대상에서 앱을 실행하며, Xcode 테스트와 Archive를 수행하는 단계가 macOS 영역입니다. 특히 서명과 배포용 내보내기는 Apple 도구 체인과 인증 자원을 함께 사용하므로 Windows나 Linux의 공유 코드 검사와 분리해야 합니다.

원격 Mac에서 Kotlin XCFramework를 어떻게 검증하나요?

먼저 저장소를 새 작업 폴더에 복제한 뒤 필요한 iOS 기기와 시뮬레이터 대상을 모두 지정해 XCFramework를 생성합니다. 이후 산출물의 포함 아키텍처를 확인하고 Xcode에서 모듈을 실제로 가져옵니다. Gradle 로그, 산출물 목록, 모듈 import 결과와 동일 입력으로 다시 생성한 기록을 함께 보관해야 단일 대상 성공을 배포 가능 상태로 오해하지 않습니다.

Kotlin Multiplatform iOS 프로젝트를 CI에서 자동 Archive하려면 어떻게 구성하나요?

의존성 복원, Kotlin Framework 생성, Xcode 빌드와 테스트, Archive, 배포용 내보내기를 각각 관찰 가능한 단계로 나눕니다. 각 단계에는 입력 경로, 출력 산출물, 실패 시 중지 조건을 둡니다. 인증서와 프로파일은 저장소나 일반 로그에 넣지 않고 비밀 저장소에서 주입하며, 마지막에는 사람의 화면 조작 없이 Archive와 산출물 검증이 끝나야 합니다.

Kotlin iOS 빌드 노드에는 어떤 Gradle과 Xcode 캐시를 보관해야 하나요?

Gradle 의존성 캐시, Kotlin/Native 관련 캐시, Xcode Derived Data와 패키지 의존성 캐시는 서로 다른 영역으로 관리합니다. 먼저 로그에서 실제 적중 여부를 확인한 뒤 보관 범위를 정해야 합니다. 여러 작업이 같은 폴더나 시뮬레이터를 공유하지 않도록 프로젝트별 작업 공간과 실행 자원을 분리하고, 캐시를 삭제한 새 작업도 정상 완료되는지 확인해야 합니다.

Kotlin 2.4.10 iOS 빌드: 2026 원격 Mac CI 배포 방법

Windows 또는 Linux를 주 개발 환경으로 사용하면서 Kotlin Multiplatform iOS 앱을 배포해야 하는 개발자를 위한 글입니다. 공유 코드 작업과 Apple 빌드 작업의 경계를 나누고, Framework 생성부터 Xcode 테스트, 서명, Archive, 재시작 복구까지 원격 Mac CI의 검증 기준을 설명합니다.

Kotlin 공식 문서는 iOS 기기용 iosArm64와 iOS 시뮬레이터용 iosSimulatorArm64를 서로 다른 빌드 대상으로 구분합니다. Kotlin의 iOS 대상 지원 문서가 설명하듯, Windows 또는 Linux에서 공유 코드 작업을 진행하더라도 Framework 통합, 시뮬레이터 검증, Xcode 테스트와 최종 Archive는 실제 macOS 환경으로 보내야 합니다. 이번 주에는 원격 Mac을 독립 Apple 빌드 노드로 만들고, 새 복제본부터 재시작 복구까지 검증하는 것이 맞습니다.

이 글이 필요한 개발자

이 글은 Windows 또는 Linux를 주 개발 환경으로 사용하면서 Kotlin Multiplatform iOS 앱을 납품해야 하는 개발자를 위한 내용입니다. Kotlin/Native와 Xcode 빌드를 CI에 연결하려는 모바일 DevOps 엔지니어에게도 해당합니다.

공유 원격 Mac의 서명 자원, 작업 폴더와 캐시를 관리해야 하는 플랫폼 담당자라면 단순히 빌드 명령이 성공하는지보다 아래의 종료 조건을 확인해야 합니다.

먼저 나누는 작업 경계

주 개발 환경에는 공통 소스, 대부분의 Gradle 검사, 코드 리뷰와 일반적인 테스트를 둡니다. 원격 Mac에는 iOS 대상 Framework 생성, Xcode 프로젝트 연결, Apple 시뮬레이터 실행, Xcode 테스트, Archive와 서명을 둡니다.

이 경계를 섞으면 세 가지 문제가 생깁니다. 첫째, Windows나 Linux에서 통과한 Gradle 결과가 iOS 앱 통합 성공을 보장하지 않습니다. 둘째, 개발자의 로컬 경로와 대화형 Xcode 설정이 CI에 숨어 새 작업 폴더에서 재현되지 않을 수 있습니다. 셋째, 서명 키와 시뮬레이터를 공유 노드의 전역 상태로 두면 동시 실행 중인 다른 작업이 결과를 오염시킬 수 있습니다.

작업 흐름은 다음처럼 고정하는 편이 좋습니다.

주 환경의 저장소와 빌드 설정이 원격 Mac 작업 폴더로 전달됩니다.
원격 Mac은 의존성을 복원하고 Kotlin/Native Framework를 생성합니다.
Xcode가 해당 Framework를 가져와 테스트하고 Archive를 만듭니다.
로그, xcresult, Framework와 Archive를 보존합니다.
실패하면 다음 단계로 넘어가지 않고 원인과 입력을 함께 남깁니다.

경계 판정: 새 작업 폴더에서 저장소를 처음부터 복제했을 때 Apple 빌드 단계까지 도달하지 못한다면, 현재 CI는 개발자의 로컬 상태에 의존하는 것입니다. 캐시를 지우기 전에 이 검사를 먼저 통과시켜야 합니다.

구성 선택과 판단 점수

Kotlin 2.4.10 iOS 빌드는 Framework를 어떤 방식으로 Xcode에 전달하느냐에 따라 운영 책임이 달라집니다. Kotlin의 네이티브 바이너리 생성 문서는 기기와 시뮬레이터 대상에 맞는 바이너리 생성 방식을 설명하므로, 단일 대상의 성공만으로 배포 완료를 선언해서는 안 됩니다.

구성	적합한 저장소와 팀 상황	CI가 관리할 것	결정 점수
직접 통합	앱과 공유 모듈을 한 저장소에서 함께 변경하는 팀	Gradle 호출, Build Phase, 경로와 실행 순서	빠른 반복 5점
CocoaPods 연동	기존 iOS 의존성 흐름과 개발자 도구가 이미 Pod 중심인 팀	설치 상태, 스크립트 단계, Pod와 Framework 연결	통합 일관성 4점
XCFramework 배포	공유 모듈을 별도 산출물로 배포하거나 여러 앱이 소비하는 팀	기기·시뮬레이터 대상, 버전, 산출물 보관	배포 격리 5점
원격 바이너리 의존성	앱 팀과 모듈 팀의 릴리스 주기가 다른 조직	바이너리 주소, 무결성, 롤백 버전	팀 분리 4점

저장소에서 앱과 공유 코드가 함께 바뀌면 직접 통합이 단순합니다. 여러 앱에 같은 모듈을 배포한다면 XCFramework가 경계를 분명하게 만듭니다. Swift Package Manager를 선택한다면 Kotlin 공식 SPM 내보내기 안내의 패키지 생성과 연결 조건을 확인하고, CI에 개발자 개인 경로가 남지 않았는지 점검해야 합니다.

Framework 산출물과 Xcode 연결

먼저 프로젝트의 Kotlin 대상 선언을 확인합니다. iosArm64는 실제 iOS 기기용이고, iosSimulatorArm64는 Apple Silicon 환경의 시뮬레이터용입니다. Intel 시뮬레이터 또는 다른 실행 환경을 지원한다면 프로젝트가 선언한 추가 대상과 실제 실행 노드의 조합도 별도로 확인해야 합니다. 대상 이름을 추측해 추가하지 말고 Kotlin Multiplatform iOS 통합 개요에 맞춰 현재 프로젝트 설정을 대조합니다.

원격 Mac에서는 저장소마다 고유한 작업 경로를 만듭니다. 그 뒤 다음 순서로 실행합니다.

저장소를 새 폴더에 복제하고 gradlew 실행 권한을 확인합니다.
프로젝트가 요구하는 의존성을 복원합니다.
기기용과 시뮬레이터용 Framework 또는 XCFramework 생성 작업을 실행합니다.
산출물 내부의 대상과 아키텍처를 검사합니다.
Xcode 프로젝트의 Build Phase가 올바른 Gradle 작업과 연결되는지 확인합니다.
Scheme, 구성 파일, 출력 경로에 개인 컴퓨터의 절대 경로가 없는지 검색합니다.
공유 코드를 수정한 뒤 새 Framework가 Xcode 앱에 실제로 반영되는지 확인합니다.

Framework가 생성됐다는 로그만으로는 충분하지 않습니다. 산출물 목록, 대상별 포함 여부, Xcode 모듈 import 성공, 같은 커밋을 다시 빌드한 기록을 남겨야 합니다. 수정한 공통 코드가 앱에 반영되지 않는다면 캐시 문제가 아니라 Build Phase 호출 순서나 출력 경로가 잘못되었을 가능성이 큽니다.

테스트 로그와 실행 환경

테스트는 하나의 명령으로 뭉치지 말고 책임을 나눕니다. 공통 코드 테스트가 실패하면 주 개발 환경과 Gradle 구성을 먼저 봅니다. Kotlin/Native 테스트가 실패하면 원격 Mac의 대상 설정, 네이티브 의존성과 컴파일 로그를 확인합니다. Xcode 테스트가 실패하면 Scheme, Framework 연결, 시뮬레이터 상태와 Apple 서명 설정을 분리해 조사합니다.

시뮬레이터 검증에는 실행 대상, 런타임, 그래픽 세션이 모두 필요합니다. SSH만 연결된 노드에서 모든 UI 상호작용이 가능하다고 가정하면 안 됩니다. Apple의 Xcode 빌드 및 실행 문서를 기준으로 명령줄 실행과 화면 기반 디버깅을 구분하십시오.

각 실행에서는 종료 코드만 보관하지 말고 테스트 결과 번들, 표준 출력, 표준 오류와 산출물 경로를 저장합니다. Xcode 결과는 xcresult 형태로 보존하면 어떤 테스트와 대상에서 실패했는지 나중에 다시 확인할 수 있습니다. 이 기록이 없으면 원격 노드 장애와 코드 회귀를 구별하기 어렵습니다.

주의: 시뮬레이터가 실행된다는 사실은 배포용 Archive가 가능하다는 뜻이 아닙니다. 시뮬레이터 대상, 기기 대상, 서명된 Archive를 각각 통과시켜야 합니다.

Archive와 서명 단계

CI 작업은 의존성 복원, Kotlin Framework 생성, Xcode 빌드와 테스트, Archive, 배포용 내보내기로 나눕니다. 각 단계에 입력, 출력, 중지 조건을 기록하면 실패한 지점에서 재실행할 수 있습니다.

서명 자원은 저장소와 분리합니다. 인증서, 설명 파일, 팀 식별자와 개인 키를 일반 로그에 출력하지 마십시오. 비밀 값은 CI의 비밀 저장소에서 주입하고, 빌드 로그에는 이름이나 지문처럼 식별에 필요한 최소 정보만 남기는 구성이 안전합니다. Apple의 배포용 빌드 작업 문서는 배포 빌드의 흐름을 확인하는 기준으로 사용할 수 있습니다.

Archive 단계의 합격 조건은 단순한 명령 성공이 아닙니다.

새 작업 폴더에서 의존성 복원이 완료됩니다.
기기용 산출물이 올바른 대상과 함께 생성됩니다.
Xcode 테스트 결과와 xcresult가 보관됩니다.
Archive가 지정된 출력 위치에 생성됩니다.
내보낸 산출물의 서명과 번들 식별자를 검사합니다.
실패 시 이전에 승인된 산출물을 보존하고 새 산출물은 배포하지 않습니다.

등록된 기기 배포를 포함한다면 Apple의 기기 배포 문서와 현재 팀의 인증 절차를 함께 확인하십시오. 개발자 개인 계정과 CI 전용 배포 자원을 분리하면 퇴사, 키 교체와 권한 변경이 빌드 전체를 멈추게 할 가능성을 줄일 수 있습니다.

캐시와 공유 노드 운영

Kotlin iOS 빌드에서 캐시는 하나의 폴더가 아닙니다. Gradle 의존성 캐시, Kotlin/Native 캐시, Xcode Derived Data, 패키지 의존성을 서로 다른 범위로 기록하십시오. 캐시를 무조건 유지하면 오래된 산출물이 섞일 수 있고, 매번 모두 삭제하면 복원 비용과 네트워크 의존성이 커집니다.

먼저 캐시 적중 로그와 생성 시점을 확인합니다. 이후 다음 규칙을 적용합니다.

프로젝트와 커밋별 작업 폴더를 분리합니다.
동시에 실행되는 작업이 같은 Derived Data와 시뮬레이터를 사용하지 않게 합니다.
서명 자원은 작업 간 공유를 최소화합니다.
캐시 삭제 후에도 새 복제본이 성공하는지 주기적으로 확인합니다.
캐시 키에는 운영체제, Xcode 도구 체인과 프로젝트 입력을 반영합니다.

CI 실행기를 여러 작업에 연결한다면 라벨로 Apple 빌드 노드를 구분할 수 있습니다. 자체 관리 실행기의 라벨 적용 문서를 참고해 iOS 전용 작업만 해당 노드로 보내고, 일반 Linux 작업이 서명 자원을 점유하지 않도록 구성하십시오.

노드 복구는 다음의 실제 장애 순서로 검증합니다.

SSH 연결을 끊고 실행 중인 작업이 기록을 남기는지 확인합니다.
호스트를 재시작한 뒤 실행기와 필요한 서비스를 확인합니다.
중단된 작업을 같은 작업 폴더에서 무작정 이어서 실행하지 않습니다.
새 작업 폴더로 다시 예약해 의존성, Framework와 테스트를 재실행합니다.
동일한 커밋의 Archive가 기존 승인 결과와 구분되어 보관되는지 확인합니다.

이 과정을 통과하지 못하면 해당 Mac은 장기 CI 노드가 아니라 수동 빌드용 원격 개발 장비에 가깝습니다.

이번 주 배포 순서

이번 주에는 기능을 더 추가하기보다 독립 테스트 저장소로 경계를 증명하십시오.

첫 작업은 Windows 또는 Linux에서 공유 코드 검사와 저장소 재현성을 확인합니다.
다음 작업은 서울 원격 Mac 노드처럼 접근 위치를 선택한 뒤 새 복제본을 만듭니다.
이어서 기기용과 시뮬레이터용 Framework를 각각 생성하고 산출물 검사를 남깁니다.
Xcode Scheme과 Build Phase가 개인 경로 없이 실행되는지 확인합니다.
Kotlin 테스트와 Xcode 테스트의 결과 번들을 보관합니다.
서명 정보를 주입해 사람이 화면을 누르지 않는 Archive를 실행합니다.
마지막으로 SSH 단절과 호스트 재시작 뒤 새 작업 폴더에서 같은 흐름을 재실행합니다.

원격 Mac 배포 위치를 아직 정하지 않았다면 VPSMAC의 원격 Mac 노드 목록에서 팀의 접근 지연, 운영 시간과 격리 요구를 먼저 비교하십시오. 지역 선택보다 중요한 것은 Xcode 버전, 서명 자원과 작업 공간을 고정하고 검증 가능한 로그를 남기는 일입니다.

현재 Windows 또는 Linux만으로 계속 운영하면 Apple 전용 Framework 연결을 로컬에서 확인하기 어렵고, 시뮬레이터와 Xcode 테스트를 마지막 단계에 몰아 실패 원인을 늦게 발견하며, 개인 Mac의 인증서와 경로에 의존하는 운영 상태가 남을 수 있습니다. 반대로 VPSMAC의 실제 원격 Mac을 먼저 임시 Apple 빌드 출구로 사용하면 전체 구매 전에 새 복제본, XCFramework, 테스트, Archive와 재시작 복구를 순서대로 검증할 수 있습니다. 장기 고정 부하나 물리 인터페이스가 필요하다면 직접 Mac을 구입하는 편이 맞지만, 팀이 안정적인 임시 CI와 배포 검증 환경을 찾는 단계라면 이 방식이 더 현실적입니다.