XcodeGen 공식 문서는 프로젝트 규격 형식으로 YAML과 JSON을 안내합니다. 이 두 형식 중 하나를 저장소에서 관리하고, 원격 Mac CI 작업에서 XcodeGen으로 프로젝트를 만든 다음 Xcode 도구로 빌드와 테스트를 실행하세요. 생성 명령이 성공했는지만 보지 말고, 깨끗한 체크아웃에서 팀의 실제 빌드 절차까지 통과하는지 확인해야 합니다.
이 글은 여러 Apple 플랫폼 타깃을 관리하며 프로젝트 설정을 검토 가능한 형태로 유지하려는 개발자에게 적합합니다.
CI 엔지니어는 프로젝트 생성 단계와 Xcode 빌드 단계를 분리해 실패 위치를 찾는 기준을 얻을 수 있습니다.
원격 Mac을 쓰는 소규모 팀은 개인 개발자의 로컬 설정에 기대지 않는 검증 흐름을 설계할 수 있습니다.
XcodeGen 원격 Mac CI에서 각 도구가 맡을 일
XcodeGen은 저장소의 프로젝트 규격에서 Xcode 프로젝트를 생성합니다. 원격 Mac은 생성된 프로젝트를 Apple 도구 체인으로 빌드하고 테스트합니다. 따라서 XcodeGen은 프로젝트 구조를 선언하고 만드는 단계이며, 컴파일 성공이나 테스트 통과를 보장하는 도구는 아닙니다.
| 단계 | 맡는 일 | 확인할 입력과 결과 |
|---|---|---|
| 프로젝트 규격 | 타깃, 파일, 빌드 설정 등을 선언 | 저장소에서 관리하는 project.yml 또는 JSON 규격 |
| XcodeGen | 규격을 읽고 Xcode 프로젝트 생성 | 생성 경로, 타깃, 스킴, 주요 빌드 설정 |
| 원격 Mac의 Xcode | 프로젝트 또는 워크스페이스 빌드와 테스트 | 선택한 Xcode, 의존성, 시뮬레이터 또는 빌드 대상 |
| CI 실행기 | 단계를 정해진 순서로 실행하고 로그 보관 | 작업 디렉터리, 인증 정보, 캐시와 정리 정책 |
Apple은 xcodebuild를 포함한 명령줄 도구를 Xcode와 함께 제공합니다. 실행 호스트에서 사용할 Xcode와 프로젝트 요구 사항이 맞는지 확인해야 합니다. 원격 Mac의 연결 방식과 운영 조건은 팀 환경에 따라 다르므로, 시작 전에 원격 Mac 지원 안내에서 필요한 접속 정보를 확인하세요.
준비 단계: 저장소와 CI 입력을 먼저 고정합니다
CI에서 project.yml로 프로젝트를 어떻게 생성하나요?
생성 명령만 작업 파일에 넣기 전에 저장소의 입력을 정리하세요. 소스 디렉터리, 프로젝트 규격 파일, 의존성 설정, 필요한 환경 변수, 타깃과 스킴을 함께 점검합니다. 규격 파일이 저장소 루트에 없다면 CI가 실행될 경로에서 파일을 찾도록 경로를 명시해야 합니다.
다음 항목은 개인 Mac에서만 우연히 설정되어 있는 값이 아니라, 새 작업 환경에서도 확인할 수 있어야 합니다.
- 프로젝트가 요구하는 Xcode 버전과 선택 방식
- 패키지나 의존성을 설치하는 명령과 잠금 파일
- 빌드에 필요한 환경 변수와 비밀 정보의 전달 방식
- 생성 결과를 저장할 경로와 빌드에 사용할 타깃 및 스킴
- 작업이 실패했을 때 생성 단계와 빌드 단계의 로그 구분
CI 비밀 정보에 서명 인증서나 배포 자격 증명이 포함된다면 저장소에 기록하지 말고, 실행 환경의 비밀 정보 관리 기능으로 전달하세요. GitHub의 자체 호스팅 실행기 보안 안내는 실행기와 작업 환경의 신뢰 범위를 검토할 때 참고할 수 있습니다. 실행기가 여러 작업을 처리한다면 이전 작업의 파일, 키체인 상태, 임시 자격 증명이 다음 작업에 남지 않는지도 확인해야 합니다.
생성 단계: 명령 성공과 프로젝트 유효성을 나눠 봅니다
원격 Mac에서 생성된 Xcode 프로젝트를 무엇으로 검증하나요?
프로젝트 작업 디렉터리에서 XcodeGen 공식 사용 안내에 따라 규격 파일을 지정해 생성합니다. 예를 들면 xcodegen generate --spec project.yml입니다. 실제 옵션과 설치 방법은 XcodeGen 공식 사용 문서를 기준으로 확인하세요.
그다음 생성된 경로가 예상 위치인지 확인하고, xcodebuild -list -project App.xcodeproj처럼 프로젝트 목록을 조회해 타깃과 스킴을 확인합니다. 프로젝트 이름과 경로는 저장소에 맞게 바꿔야 합니다. XcodeGen이 종료 코드 0을 반환해도, 필요한 스킴이 없거나 빌드 설정이 의도와 다르면 생성 결과를 승인하면 안 됩니다. 스킴의 빌드 및 테스트 동작은 Apple의 스킴 구성 안내와 프로젝트 자체 설정을 대조하세요.
빌드 단계: 의존성 처리 다음에 xcodebuild를 실행합니다
Xcode 프로젝트가 생성되면 CI에서 프로젝트 또는 워크스페이스를 명시하고, 스킴과 빌드 대상을 선택합니다. 기본 흐름은 아래와 같습니다. 시뮬레이터 이름과 대상은 실행 호스트에 실제로 설치된 환경에 맞춰 지정해야 합니다.
xcodegen generate --spec project.yml
xcodebuild -project App.xcodeproj -scheme App build
xcodebuild -project App.xcodeproj -scheme App test
저장소가 CocoaPods 등으로 워크스페이스를 사용하는 경우, 프로젝트 대신 실제 생성된 워크스페이스를 선택해야 합니다. 의존성 설치는 프로젝트의 잠금 파일과 팀 정책을 따르세요. CocoaPods의 install과 update 동작 설명에 따르면 두 명령은 의존성 버전을 다루는 목적이 다르므로, CI에서 무심코 업데이트 명령을 쓰면 로컬 개발 때와 다른 입력으로 빌드될 수 있습니다.
| 설정 항목 | CI에서 확인할 내용 | 흔한 실패 원인 |
|---|---|---|
| 프로젝트 선택 | .xcodeproj 또는 필요한 .xcworkspace |
의존성 설치 뒤 사용할 파일이 달라짐 |
| 스킴 | 빌드와 테스트에 사용할 스킴 | 공유되지 않은 스킴 또는 잘못된 이름 |
| 빌드 대상 | 실제로 사용 가능한 대상과 런타임 | 실행 호스트에 해당 대상이 없음 |
| 의존성 | 잠금 파일과 설치 단계가 일치하는지 | 설치 단계에서 버전이 달라짐 |
| 결과 판정 | 빌드와 테스트 로그를 각각 보관 | 생성 성공을 전체 작업 성공으로 오인 |
Apple의 명령줄 도구 참고 자료와 Xcode 빌드 명령 안내를 함께 확인하면 프로젝트와 워크스페이스 선택, 빌드 실행 방식을 점검하는 데 도움이 됩니다. 테스트 단계는 빌드와 별도 결과로 남기세요. Apple의 자동화 테스트 안내를 참고해 테스트 실행과 판정 기준도 팀의 CI 흐름에 맞추면 됩니다.
버전 관리와 재실행은 팀의 생성 정책으로 결정합니다
XcodeGen이 만든 프로젝트 파일을 Git에 커밋해야 하나요?
모든 저장소에 적용되는 단일 답은 없습니다. XcodeGen FAQ는 생성 파일 관리와 관련된 선택지를 설명하지만, 실제 정책은 팀이 프로젝트 파일을 검토하고 사용하는 방식에 맞춰 정해야 합니다. XcodeGen 자주 묻는 질문을 참고하되, 생성물을 커밋할지 여부는 저장소의 빌드 흐름과 검토 절차로 결정하세요.
| 운영 방식 | 장점 | 주의할 점 |
|---|---|---|
| 생성된 프로젝트를 커밋하지 않음 | 규격 파일을 설정의 기준으로 두기 쉬움 | 각 빌드에서 생성 단계를 반드시 실행해야 함 |
| 생성된 프로젝트도 커밋함 | 생성 결과를 코드 리뷰에서 확인 가능 | 규격과 생성 파일이 어긋나지 않는지 점검해야 함 |
프로젝트를 커밋하지 않는다면 CI에서 생성 누락이 생기지 않도록 하고, 커밋한다면 깨끗한 체크아웃에서 다시 생성한 결과가 예측 가능한지 검토하세요. 어느 쪽이든 규격 파일, XcodeGen 버전, 의존성 설치 절차를 함께 기록하는 것이 중요합니다. 재생성 결과의 차이를 검토할 수 없다면 빌드 실패가 설정 변경 때문인지 도구 버전 변경 때문인지 찾기 어려워집니다.
생성부터 테스트까지 깨끗한 체크아웃에서 어떻게 확인하나요?
개발자의 작업 폴더에는 캐시나 로컬 설정이 남아 있을 수 있습니다. 그러므로 최종 승인은 깨끗한 체크아웃을 기준으로 하세요. 다음 목록은 CI에 적용할 수 있는 실행 순서입니다.
- [ ] 저장소를 새 작업 폴더에 체크아웃하고 필요한 Xcode를 선택합니다.
- [ ] 프로젝트 규격 파일과 잠금 파일이 저장소에 있는지 확인합니다.
- [ ] 프로젝트 정책에 맞춰 의존성을 설치하고 설치 결과를 로그에 남깁니다.
- [ ] XcodeGen으로 프로젝트를 생성하고 생성 경로와 종료 상태를 기록합니다.
- [ ] 타깃과 스킴을 확인한 뒤 대표 빌드를 실행합니다.
- [ ] 대표 테스트를 실행하고 빌드 결과와 분리해 판정합니다.
- [ ] 생성 결과의 변경 여부를 저장소 정책과 대조하고, 같은 입력으로 다시 실행합니다.
생성 단계의 실패와 Xcode 빌드 또는 테스트의 실패를 별도 로그로 남기면 원인을 좁히기 쉽습니다. 두 실행에서 차이가 생기면 먼저 규격 파일, XcodeGen 버전, 의존성 입력, 선택한 Xcode를 비교하세요. 빌드 시간 개선을 검토하는 경우에도 추측으로 병목을 정하지 말고 Apple의 빌드 시간 측정 안내에 따라 실제 빌드 기록을 살펴보세요.
원격 Mac으로 지속 CI를 운영할지 판단합니다
한 번의 생성 성공만으로 지속 빌드 환경을 승인하지 마세요. 프로젝트가 요구하는 의존성 설치부터 빌드와 테스트까지 깨끗한 체크아웃에서 반복해 보고, 결과가 팀의 버전 관리 정책과 일치하는지 확인하세요. 아래 조건이 충족되면 다음 CI 작업으로 확대할 근거가 생깁니다.
- 프로젝트 규격과 도구 버전을 리뷰할 수 있습니다.
- 실패한 단계가 생성, 의존성 설치, 빌드, 테스트 중 어디인지 로그로 구분됩니다.
- 재실행 결과가 저장소의 생성 파일 정책과 일치합니다.
- 비밀 정보와 실행기 상태가 작업 간에 안전하게 관리됩니다.
현재 개인 Mac이나 다른 빌드 환경에 의존하면 로컬 설정 차이, 장비 점유, 작업 이력 분산이 운영 부담이 될 수 있습니다. 반대로 고정된 물리 장비가 계속 필요하거나 주변 장치에 직접 연결해야 한다면 원격 Mac 임대가 적합하지 않을 수 있습니다. 일시적인 Xcode 호환성 확인이나 팀 공용 CI 검증 환경이 필요하다면, 원격 접속과 운영 방식은 자주 묻는 내용에서 확인하고 필요한 기간에 맞춰 osxmesh 요금제 안내를 살펴보세요. 먼저 깨끗한 체크아웃에서 프로젝트의 실제 빌드와 테스트를 통과시키고, 그 작업을 지속 운영할 이유가 확인된 뒤 환경을 선택하는 편이 안전합니다.